clean-code

Clean Code And Clean Architecture

首次编辑前：加载上下文

你会忘记之前会话中的所有内容。scripts/ 和 references/ 均相对于此文件所在文件夹解析。按顺序阅读；琐碎编辑（拼写错误、注释）可跳过此步骤和审查清单。

1. 技术栈。 .clean/context.json；若缺失：运行 scripts/detect_stack.py，或查看清单文件和文件扩展名。
2. 工具包。 使用文件读取工具打开 packs 中的每个工具包，或打开“Read next”下列出的工具包（仅指出工具包名称不等于已阅读），但 pack_scopes 不包含你负责范围的框架工具包除外。手动查阅：references/framework-map.md 中的 clean-packs 索引；若没有，则回答其中的适配问题。
3. 分层。 .clean/architecture.md；参见分层规则。
4. 决策。 .clean/decisions.md、.clean/ledger.md。已记录的决策已定；继续进行中的工作，不要重新开始。
5. 结构。 你负责区域对应的 .clean/structure.md 条目（grep 路径），或运行 scripts/map_structure.py --path <area>；手动操作时，列出文件夹，并打开两三个最相似的文件。
6. 项目说明。 AGENTS.md、CLAUDE.md、CONTRIBUTING.md、ARCHITECTURE.md、README.md。

发生冲突时，优先级从高到低依次为：项目说明、已记录的决策、已声明的分层、本地约定、框架工具包、语言工具包、本技能。只有 init、audit、new-project 会创建 .clean/；普通会话只读取它，并在结束时询问是否要将信息持久化。

操作流程

1. 明确范围：行为变更、假设、最小范围、成功检查。只有当歧义会改变实现时才提问。
2. 阅读相邻代码、命名、测试、错误风格和框架惯用写法；先搜索现有实现。
3. 确定位置：所属单元；位于哪条边界的哪一侧。
4. 精确编辑：每一处修改都必须对应请求；进行有针对性的编辑，绝不重新生成整个文件；移除因你的修改而成为孤项的内容。
5. 验证：执行最精简且有意义的检查，然后根据风险级别完成相应验证（review-checklist.md）；修复错误：先编写复现测试；重构：前后都运行测试。未经实际运行，不得声称成功。
6. 使用 references/review-checklist.md 审查差异，并进行自检。

始终适用的规则

文件位置。 根据角色确定文件夹，并遵循各项目包的角色和项目布局；镜像相似文件。只有在没有合适归属位置时才新建文件，并确保完整接入：导入、导出、注册、路由、依赖注入和构建配置；未被引用的文件就是死代码。绝不默认使用仓库根目录或当前目录。绝不创建同级变体（_v2、_new、_final、_copy），也不把杂项塞进“杂物抽屉”（utils、helpers、common）；按概念命名。使用最窄的访问修饰符。

每个单元只做一件事，适用于所有规模：描述时需要用“和”？拆分。解析、领域规则、持久化、外部调用、展示、组装：各有独立归属。编排器负责协调调用，不包含业务规则。新行为应放入其所属单元，而不是当前打开的文件。不同参与方的代码必须分开，即使目前完全相同。

最少代码。 编写代码前，遇到第一个肯定答案就停止：不需要（YAGNI）？什么都不写。代码库中已有？复用。标准库、平台或已安装的依赖能实现？使用它。只需一行？就写一行。否则写最少的代码。绝不删减安全措施：验证、错误处理、安全性、无障碍性。

代码。 名称应使用项目词汇表达意图，每个概念用一个词。函数：只做一件事，保持在一个抽象层级，参数尽量少，不用标志参数。注释：简要说明原因。绝不吞掉错误：在能够做出决策的地方处理，并保留原因；将预期结果建模为值。测试：遵循 TDD 三定律和 F.I.R.S.T.；绝不弱化、跳过或删除失败的测试。根据 .clean/context.json 中已安装的版本核实每个 API，绝不凭记忆。仅当副本必须同步修改时才去重（DRY）。格式交由格式化工具处理。设计优先级：测试通过、不重复知识、表达意图、元素尽可能少。

安全。 在每个信任边界验证并编码输入，为查询使用参数化，将授权逻辑放在其保护的操作旁，绝不将机密写入代码、已提交的配置或日志。

已声明分层时的分层规则

如果 .clean/architecture.md 声明了分层，则必须严格遵守：使用 scripts/check_boundaries.py 检查，或阅读已更改文件的导入，并为每个分层命名。未声明分层时：遵循框架项目包的惯用结构；这些规则用于辅助判断。

• 依赖规则：源码依赖只能指向内层，即更高层级的策略；内层不得引用任何外层内容（类、函数、变量、注解、数据格式）。
• 业务规则处于最高层；数据库、Web、UI、框架和交付机制都是由策略拥有的接口背后的细节。
• SQL 只能放在数据访问层。行数据、ORM 类型、框架请求／响应对象绝不能传入内层；应传递为内层所需结构设计的简单数据结构。
• 绝不从框架基类派生业务对象，也不为其添加注解；在 main 中进行依赖注入组装。
• 组件图必须无环；依赖应指向更稳定的组件；将难测部分与易测部分拆开；不要臆测边界。

命令

/clean-code <argument>（或 $clean-code、@clean-code、/skill:clean-code）以及自然语言请求的路由方式完全相同。

Argument	遵循
init（别名 questions、"interview me"）	references/init.md
audit	references/audit-report.md；不修改代码
clean-up	使用 .clean/ledger.md 执行 references/project-refactor.md；若无 ledger：提出审计方案（文件数量），等待同意
new-project <description>	references/new-project.md
plan <task>	references/plan.md；不修改任何内容
review [files]	references/review-checklist.md、review 命令；不修改任何内容
compress [files]	references/compress.md；绝不触碰受管理的代码块
（无）	本文件；对于多步骤或可恢复的工作，使用 references/session-protocol.md

加载计划

只从 references/ 中读取任务所需内容；长文件通过其目录查阅：

任务	阅读
审查；Agent 异味 A1-A10	review-checklist.md
风险级别：LOW、MEDIUM、HIGH	review-checklist.md、Risk Levels
注释清理（C1-C5、G12）	comments.md
架构风格、设计模式、数据访问	patterns.md
新增依赖	framework-map.md、Dependencies And Package Idioms
新增边界、层、框架或数据库	architecture.md
测试	tests.md
并发	concurrency.md
安全、信任边界、数据与对象、性能	principles.md
异味命名或分类	smell-triage.md；ID（G17、N7、T5 等）见 chapter-map.md
确切命名的规则	canon.md
下一次会话的状态	memory-protocol.md
已完成的示例、模板	examples.md
宿主钩子、命令、安装路径	host-matrix.md
脚本 detect_stack.py、scan_repo.py、map_structure.py、check_boundaries.py、check_compression.py：标志、发现项、退出码；输出仅作为证据，不作为结论	tools.md

范围模式

小范围修改（默认）：只处理最小范围；报告无关异味，除非请求的结果需要修复（“让测试套件通过”），否则不要修复；只做最小修复，并单独报告，绝不削弱测试。 专项改造（仅限明确请求）：references/project-refactor.md；改造批次中绝不改变行为。

完成检查清单

• 首次编辑前已阅读相关资料包。
• 已完成任务；每处改动都可追溯至任务，并遵守上述规则。
• 新文件已按职责放置并接入；不存在同类变体、重复项、死代码、临时文件或调试输出。
• 测试覆盖了改动；没有削弱任何测试。
• 如实报告验证情况：风险级别、结果、未运行的内容及剩余风险。
• 持久性决策已记录在 .clean/decisions.md；新增或移动了文件且 .clean/ 存在时，已运行 scripts/map_structure.py --write。