code-standards

代码规范——变更工作流

你正在进行代码变更。本技能规定了执行顺序，不依赖特定技术栈。开始前，先阅读项目自己的文档（README、CONTRIBUTING、AGENTS.md/CLAUDE.md、Makefile 或 package 脚本），了解项目的构建、测试、lint 和格式化命令；所有命令都应适配项目的实际工具链。

步骤

1. 了解情况。 阅读项目中的经验教训或易错点文件（例如 tasks/lessons.md），并遵守其中的要求。 找到并阅读与你要修改的子系统相关的那份文档，不要遍历整个目录树。
2. 非简单变更先规划（3 步及以上，或涉及架构选择）：在 tasks/todo.md 中简要列出计划——要修改的文件、要添加的测试、风险。进展偏离计划时，停止并重新规划。
3. 基线： 在动手修改之前，先让项目的构建和测试命令全部通过。已有失败就是首要任务；绝不要在损坏的基线上继续工作。
4. 实现： 用最小改动修复根本原因。手动遵循周边代码风格。 不要对你修改的文件运行批量自动格式化工具；这会让真正的差异淹没在无关改动中。
5. 测试： 新行为必须有对应测试，且在没有该变更时测试会失败；安全防护必须有否定断言测试（错误令牌 → 拒绝，状态不变，不泄漏数据）。
6. 验证： 在宣布“完成”之前，运行完整检查套件（构建 + lint + 类型检查 + 测试），直至全部通过。
7. 自我审查： 像审查别人的 PR 一样检查自己的差异（或调用审查技能）。在提交前修复发现的问题。
8. 收尾： 在同一变更中更新文档；如果你受到纠正或遇到意外情况，将其追加到经验教训文件中；编写符合规范的提交消息（feat|fix|docs(scope): …）。

触发条件——遇到以下情况时，暂停并重新检查项目指南……

• 修改公共或共享接口（API、线格式、模式）→ 检查每个调用方；优先采用增量式变更
• 添加依赖 → 权衡传递依赖的体量和许可证，并确认标准库是否已有相应功能
• 修改身份验证、令牌或权限 → 审查所有写入和读取路径，并添加否定测试
• 将机密写入磁盘 → 使用平台提供的原子私密创建 API，绝不要先写入再修改权限
• 在 await/阻塞调用期间持有锁，或在逻辑中读取环境变量 → 提取纯决策函数

无进展保护

同一故障连续两次修复仍然存在时，停止：将发现记录到经验教训文件中，将相应事项标记为 [BLOCKED]，并明确报告。不要反复折腾。