soia-dev-coding-protocol 是一个为普通工程代码改动建立可验证工作契约的技能，适用于代码实现、bug fix、重构和评审。它的核心目标是让每一次改动都明确：改什么、为何改、如何证明改变正确，以及哪些风险尚未覆盖。
用途
该技能为代码改动建立最小范围、验证前置、anti-fake-fix 与写后复核契约。它面向修复缺陷、实现功能、评审与重构等日常工程任务，触发场景包括「改这个 bug」「重构这段」「加个功能」。
主要能力
技能会先定义最小范围和验收证据，再做最小可靠改动，输出变更映射、测试证据和残余风险。在评审或重构时，检查行为保持、类型边界与同类模式，给出发现、复核路径和未处理项。
核心规则
-
暴露不确定性：会影响正确性、安全性、外部行为、数据完整性或 API 合约的歧义必须先问；低风险歧义采用最窄、可逆的解释并说明；认证、破坏性操作和不可逆变更不得靠猜测推进。
-
最小范围：只写完整解决当前问题所需的代码，不因顺手加入抽象、开关、重命名、格式化或「未来可能需要」的分支；发现无关问题时单独报告，不混入补丁。
-
隔离并追溯改动：每一行改动都应能映射到请求或为该改动必要的验证；沿用周边风格；只移除被本次改变淘汰的内容；修复一种模式后搜索同类调用点，再决定是否纳入范围。
-
验证结果，不验证意图：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）、跨平台（平台分支的支持或降级行为明确）、观测性（错误不被静默丢弃，失败包含足够上下文）、一致性（公开接口有必要文档，元数据与相关变更记录同步）、依赖方向（没有重复定义上层类型或制造反向依赖）。命中项必须修复，或在交付中明确说明为何暂缓及其风险。
使用方式
说明目标、目标仓库、相关文件、可观察的预期行为，以及可用的测试或复现路径。涉及认证、删除、不可逆数据变更、公开 API 或远端发布时，缺少关键约束必须先询问。
安装
claude plugin marketplace add soia-team/soia-open-skills
claude 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。
安全边界
提交、push、发布、删除、覆盖和远端状态更改需要本次请求的明确授权。执行前重新核对目标和影响范围；提交时只暂存本任务文件。
私密信息与中间数据
只读取当前任务需要的源码、配置、测试和日志片段；遇到凭据、客户数据或生产日志时最小化引用，不复制到补丁、测试 fixture 或回执。代码改动和用户要求的交付物留在目标仓库或用户指定路径。本技能不建立自己的持久 state、cache 或调用记录。测试、构建和工具产生的临时文件服从目标仓库约定；没有约定时使用操作系统临时目录，并在任务结束后清理本技能创建且可安全删除的内容。Provider 凭据只使用官方登录态或系统凭据库；普通 config.yml、命令行、日志和提交中不得保存秘密。完成回执只记录文件路径、检查命令和结果摘要，不回显秘密值、完整 prompt 或无关源码正文。
日志与完成回执
完成：<实现、修复、重构或评审结果>。
契约：<假设、范围边界、验收目标> 文件变化：<每项变更如何映射到请求> 验证：<命令、结果和独立复核> 残余风险：<未覆盖场景或「无」>
验证
运行最接近风险面的项目检查；以独立路径复核关键结论；检查工作树与暂存区，确认没有无关文件进入交付；回执只陈述实际执行的检查与结果。
适用场景与限制
适用于修复、重构、实现和评审等普通工程代码改动。强依赖目标仓库和与任务相称的验证手段；缺少验证手段时需使用最窄的可靠复现并说明限制。涉及认证、删除、不可逆数据变更、公开 API 或远端发布时，缺少关键约束必须先询问。本技能不建立自己的持久 state、cache 或调用记录。