SKILL.md
soia-dev-coding-protocol
客户可读说明
这个技能可以做什么
为代码实现、bug fix、重构和评审建立可验证的工作契约：改什么、为何改、如何证明改变正确，以及哪些风险尚未覆盖。
| 客户想要 | 技能会做 | 客户能看到 |
|---|---|---|
| 修复缺陷或实现功能 | 先定义最小范围和验收证据，再做最小可靠改动 | 变更映射、测试证据和残余风险 |
| 评审或重构 | 检查行为保持、类型边界与同类模式 | 发现、复核路径和未处理项 |
客户如何使用
说明目标、目标仓库、相关文件、可观察的预期行为，以及可用的测试或复现路径。涉及认证、删除、不可逆数据变更、公开 API 或远端发布时，缺少关键约束必须先询问。
依赖与安装
安装：
claude plugin marketplace add soia-team/soia-open-skillsclaude plugin install soia-dev@soia只要这一个技能时，可用 npx 路线。注意技能会落进共享真源 ~/.agents/skills；若同时装了插件，同一技能会出现两份索引且各自漂移，建议二选一：
npx skills add soia-team/soia-open-dev-skills -g -a '*' -s soia-dev-coding-protocol -y强依赖：目标仓库和与任务相称的验证手段。优先使用项目已有测试、lint、类型检查和 fixture；没有时使用最窄的可靠复现并说明限制。本技能无需私有配置。
WorkBuddy 的装载单位是角色化专家而不是插件，npx skills add -a '*' 覆盖不到它，需要单独安装，见 docs/install/workbuddy.md。
私密信息与中间数据
- 只读取当前任务需要的源码、配置、测试和日志片段；遇到凭据、客户数据或生产日志时最小化引用，不复制到补丁、测试 fixture 或回执。
- 代码改动和用户要求的交付物留在目标仓库或用户指定路径。本技能不建立自己的持久 state、cache 或调用记录。
- 测试、构建和工具产生的临时文件服从目标仓库约定；没有约定时使用操作系统临时目录，并在任务结束后清理本技能创建且可安全删除的内容。
- Provider 凭据只使用官方登录态或系统凭据库；普通
config.yml、命令行、日志和提交中不得保存秘密。 - 完成回执只记录文件路径、检查命令和结果摘要，不回显秘密值、完整 prompt 或无关源码正文。
日志与完成回执
完成：<实现、修复、重构或评审结果>。
契约：<假设、范围边界、验收目标>
文件变化：<每项变更如何映射到请求>
验证：<命令、结果和独立复核>
残余风险：<未覆盖场景或“无”>执行契约
写代码前明确：
- 假设：哪些来自观察、哪些是推断；
- 范围：包含什么、不包含什么；
- 验证计划：每个步骤对应的可证伪检查。
写代码后明确：改变了什么、它如何满足请求、实际运行了哪些验证、哪些真实风险仍存在。没有证据就不能称为完成。
核心规则
1. 暴露不确定性
会影响正确性、安全性、外部行为、数据完整性或 API 合约的歧义必须先问。低风险歧义采用最窄、可逆的解释并说明。认证、破坏性操作和不可逆变更不得靠猜测推进。
2. 最小范围
只写完整解决当前问题所需的代码。不要因为顺手加入抽象、开关、重命名、格式化或“未来可能需要”的分支。发现无关问题时单独报告，不混入补丁。
3. 隔离并追溯改动
每一行改动都应能映射到请求或为该改动必要的验证。沿用周边风格；只移除被本次改变淘汰的内容。修复一种模式后搜索同类调用点，再决定是否纳入范围。
4. 验证结果，不验证意图
- bug fix：可行时先复现；否则建立最窄的失败检查；
- validation logic：覆盖非法输入及预期通过路径；
- refactor：以 before/after 或行为测试证明语义保持；
- 多步任务：先写
[步骤] -> [验证]； - 测试失败、无法运行或只覆盖 happy path 时，如实报告，不能用“代码看起来对”替代证据。
Anti-Fake-Fix Gate
在宣称完成前逐项检查：
| 症状 | 要求 |
|---|---|
| 没跑验证就称完成 | 补跑真实命令或明确说明为何无法验证 |
| 用 TODO、注释或吞错代替修复 | 让行为本体满足需求，或明确将任务标为未完成 |
| 只验证自己的结论 | 使用独立路径：测试、fixture、类型检查、日志或人工复核 |
| 修一处就收口 | 搜索同类模式，说明纳入或排除理由 |
| 一次提交混入无关调整 | 拆分或移除无关改动 |
接口、trait 与 adapter 的额外契约
开始实现前，任务必须明确：
- 上下文序列化：system、消息顺序、工具、tool call/result 分别是否传递及其格式；
- 用量/计费语义：调用方如何区分计量、订阅或其他模型；接口缺表达能力时先补接口；
- 类型归属：公开表面上的类型来自本模块或明确依赖，避免复制高层类型形成 shadow enum；
- 下游影响：列出已知消费者、它们怎样使用新增方法及其验证路径。
至少验证：含 system、两轮以上消息和工具的上下文回合；用量语义；类型归属搜索；以及一条到下游消费者的完整路径。缺任何一项时停止并请求补全规格。
提交前自审
- 资源：没有不必要的逐调用客户端/进程泄漏，子进程与 stderr 都被正确处理；
- 可测可配：没有把 endpoint、二进制路径或用户输入写死到不可替换位置；
- 安全：默认值不扩大权限，不把不可信输入拼进 shell；
- 跨平台：平台分支的支持或降级行为明确；
- 观测性：错误不被静默丢弃，失败包含足够上下文；
- 一致性：公开接口有必要文档，元数据与相关变更记录同步；
- 依赖方向：没有重复定义上层类型或制造反向依赖。
命中项必须修复，或在交付中明确说明为何暂缓及其风险。
安全边界
提交、push、发布、删除、覆盖和远端状态更改需要本次请求的明确授权。执行前重新核对目标和影响范围；提交时只暂存本任务文件。
验证
- 运行最接近风险面的项目检查；
- 以独立路径复核关键结论；
- 检查工作树与暂存区，确认没有无关文件进入交付；
- 回执只陈述实际执行的检查与结果。