coding-standards

编码规范

你编写、编辑或审查的每一行代码都必须遵守这些规则。规则分为两组，每项任务都要应用通用规则 + 恰好一种框架规则：

• 通用规则（references/common/）——适用于每种语言，约束每个函数、类和模块的内部，体现整洁代码原则。
• 各框架规则（references/<framework>/）——约束外部结构：文件存放位置和文件夹含义，以及框架模式。

本文档中的所有路径都相对于此 SKILL.md 文件，因此无论技能安装在哪里，路径都能正确解析。

流程：引导（仅一次）→ 跳过排除项 → 选择模式 → 检测框架 → 确定结构 → 选择执行方式 → 打开任务列表 → 执行分支。步骤 0–6 是上述流程；步骤 7 是分支（7a 流水线，7b 内联）。

---

步骤 0 — 初始化强制执行钩子（每个会话仅一次，仅在需要时）

先运行快速只读检查（单条绝对路径命令，不带 cd/&&——符合预先批准的权限规则，因此不会提示确认）：

python3 <skill-dir>/bootstrap.py --verify

退出代码为 0 → 钩子已配置；前往步骤 1。非零 → 运行完整安装，并根据输出采取行动：

python3 <skill-dir>/bootstrap.py --auto-install

• Wired / Updated / Install OK → 告知用户重启会话以激活钩子。 在用户重启之前，本会话中的 PreToolUse 钩子不会生效（Claude Code 会在会话开始时读取 settings.json），因此此处的 Write 不会被拦截。这就是未强制执行的首会话空档。弥补方法：对于本会话中编写或审查的任何代码，在报告完成前，手动对涉及的文件运行检查器，作为补偿性检查—— python3 <skill-dir>/hooks/review-files.py <file> … 无需重启即可立即运行——并修复检查发现的问题。告知用户从下个会话开始会在写入时拦截；本会话则由手动检查器扫描。
• Blocking issues: → 原样告知用户，并暂停操作，直到用户解决问题。
• cannot determine install scope → 此技能不在 .claude/skills/ 目录树中；指出 README.md，并继续操作，不启用写入时拦截——规则仍然适用，review-files.py 仍会作为手动检查器扫描你修改的内容。

安装程序会自动检测项目级或全局安装范围，并自动安装此技能所需的软件包。标志、venv/PEP-668 回退方案和就绪状态细分见 references/bootstrap.md——仅在引导过程异常时阅读。

---

步骤 1 — 跳过排除文件（始终执行）

某些文件由第三方工具管理，而非用户管理——编辑这些文件会破坏升级路径，或导致生成的代码发生无谓变动。符合以下任一条件的文件均为排除文件：

1. 文件路径匹配内置默认规则（已安装的依赖项、生成的代码、构建输出、锁文件、ORM 迁移、shadcn components/ui/**、此技能自身的 .coding-standards/** 报告）。完整列表见： hooks/_exclusions.py → DEFAULT_EXCLUSIONS。
2. 文件的前 10 行带有生成标记（@generated、DO NOT EDIT、Code generated by 等）。
3. 文件匹配项目 .coding-standards-ignore 中的模式（位于仓库根目录，采用 gitignore 风格，由引导过程创建）。

通过检查来判定：核对路径是否匹配默认列表、正在阅读的文件中是否有标记，以及是否存在忽略文件。不要手动筛选需要审查或修复的范围——hooks/review-files.py 会自行跳过排除文件，写入时钩子也会对这些文件静默退出。

拒绝修改排除文件。如果用户明确要求编辑此类文件，请警告用户该文件由工具管理，重新生成时所做更改会丢失；只有在用户同意后才继续。

---

Step 2 — 选择模式（仅在未明确任务时激活）

如果用户的消息已经说明了任务，请跳过此步骤——例如“编写 X”“重构 Y”“审查这个 PR”“这样写是否规范？”“FN-005 是什么意思？”。这些表述本身就是模式；直接进入 Step 3。

仅当技能在没有明确任务的情况下激活时才触发此步骤：只输入 /coding-standards、“这个技能有什么用？”或过于笼统、无法推断模式的消息。使用 AskUserQuestion 提问，并采用 references/activation.md 中精确的模式选择器内容——下方路由规则会根据这些选项进行匹配。

根据回答进行路由：

• 编写符合这些规则的代码 → 进入编写模式，执行完整流程。
• 检查现有代码是否符合这些规则 → 询问要检查的内容（文件、文件夹、差异、PR）。用户回答后，检查范围便已确定——因此，在开始审查之前，立即构建完整工作流任务列表（Step 6），并将解析 + 记录结构作为第 1 项，同时将用户指定的其他目标作为更多事项纳入列表。
• 给我看看这些规则 → 静默解析框架和结构，加载参考资料，并展示一屏规则索引。不询问结构，不询问运行模式——不写入任何内容。

选择器中没有 修复 选项——它由用户的措辞触发（“修复这些问题”／“应用审查结果”，或“继续修复”／“恢复修复”，以接续尚未完成的里程碑计划），并直接进入修复模式。

每个会话最多询问一次；模式一旦确定，就保持不变。用户已经说明任务时，绝不提问。

---

Step 3 — 检测框架

查看你要处理的文件，并与下方的信号进行匹配。**遇到第一个“负责的文件类型”包含你正在编辑的文件扩展名的匹配项时，就停止。**如果某一行的文件类型不包含当前文件，即使存在仓库级信号，也跳过该行——因此，在 Laravel + Inertia/Vue 仓库中编辑 .php 文件时，解析结果是 laravel，而不是 vue-nuxt；在同一仓库中编辑 Component.vue 时，解析结果则是 vue-nuxt。这是规则；下方“更具体”的说明仅用于打破同一种语言内部的平局。

框架键	管理的文件类型	检测信号（满足任意一项即可）
nextjs	.ts .tsx .js .jsx	仓库根目录下有 next.config.{js,ts,mjs} 或 package.json 依赖中有 next 或 文件位于与该配置文件同级的 app/ 或 pages/ 目录下
react-native	.ts .tsx .js .jsx	package.json 中有 expo、react-native 或 @expo/* 或 app.json 中有 "expo" 键 或存在 metro.config.js
nativescript	.ts .js .xml	存在 nativescript.config.{js,ts}，或 package.json 中有 nativescript 或 .xml 文件与 .ts 页面文件配对
cocos-creator	.ts .js	仓库根目录下有 assets/、settings/，且 .gitignore 中有 library/ 或 temp/ 或导入 cc / cocos-creator 或存在 .scene / .prefab 文件
vue-nuxt	.vue .ts .js	package.json 中有 vue 或 nuxt 或存在 nuxt.config.{ts,js} 或存在 .vue 文件
nestjs	.ts	package.json 中有 @nestjs/* 或存在带有 NestJS 装饰器导入的 *.module.ts / *.controller.ts / *.service.ts
node-express	.ts .js	package.json 中有 express 或 fastify，且不是 NestJS
laravel	.php	composer.json 中有 laravel/framework 或根目录下有 artisan 文件 或 app/ 下有 .php 文件
csharp	.cs	存在 *.csproj、*.sln 或 *.cs 文件
spring-boot	.java .kt	pom.xml 中有 spring-boot-starter-* 或 Gradle 配置了 Spring Boot 插件 或存在 @SpringBootApplication
django	.py	存在 manage.py 和设置模块 或 pyproject.toml / requirements.txt 中有 django
fastapi	.py	依赖中有 fastapi 或存在 from fastapi import FastAPI，且不是 Django
flask	.py	依赖中有 flask 或存在 from flask import Flask，且不是 Django / FastAPI
go-http	.go	存在 go.mod 和路由器（gin、echo、fiber、chi、mux），或存在 net/http 处理程序路由
unsupported	（任意）	技能可识别但没有结构参考的框架 / 生态系统。Web：Angular（@angular/core / angular.json）、Svelte / SvelteKit（.svelte、package.json 中有 svelte、svelte.config.*）、Astro（astro 依赖 / astro.config.* / .astro）、Remix（@remix-run/*）、Ember、SolidStart、Qwik。游戏引擎：Unity（Assets/ + ProjectSettings/）、Godot（project.godot）。v5 尚未覆盖的其他生态系统：Ruby/Rails、Rust、Swift/iOS、Flutter/Dart、Android 原生开发。…
vanilla-js	.ts .js	不符合以上任何框架条件、且不属于已识别但不支持的框架的普通 .ts / .js 文件（库、CLI、脚本、无浏览器项目）

• 如果同一语言有两行规则都适用（例如，某个 .ts 文件既适用于 Next.js，也适用于 vue-nuxt）， 请选更具体的一行（在 Next.js 仓库中的 .tsx 文件属于 nextjs，而不是 react-native）。上面的文件类型 门槛已区分不同语言；这里只处理同一语言内的冲突。
• 单仓库按文件而非仓库选择框架——从文件所在位置向上查找，直到找到一个信号匹配且其文件类型包含该文件的规则。apps/web/... → nextjs；apps/api/... → nestjs。
• **引擎／生态系统覆盖规则（优先检查）：**如果项目显示出游戏引擎标记——Unity（Assets/ + ProjectSettings/）或 Godot（project.godot）——则归入 unsupported，即使 .cs 文件原本会匹配 csharp 也不例外。csharp 规则中的垂直切片 Web 布局不适用于 Unity 项目，因此引擎信号优先。common/ 的行级规则仍然适用；结构审查则不予处理。
• 没有框架信号的普通库，默认使用 vanilla-js（JS/TS），或仅使用 common/（Python）。
• 已识别但不受支持（unsupported 规则）：明确说明这一点，且不要回退到 vanilla-js——将 vanilla-js 的业务目录 + barrel 布局强加给 Angular 或 SvelteKit 应用，会与框架自身约定直接冲突，反而更糟，不如不做结构审查。改为：应用 common/ 的所有规则（这些规则是通用的——行级规则和写入时钩子仍会针对该语言生效），沿用项目现有布局进行文件放置，并告知用户此技能目前没有该框架的结构参考，因此结构／放置审查仅限于 common/structure.md（ST-*），不涉及框架特定的结构。跳过第 4 步的结构问题（没有可供选择的目录）。
• 如果无法判断，询问一次——不要在不同框架之间猜测。

---

第 4 步 — 解析项目结构（外层框架）

此步骤解析外层文件夹布局——顶层文件夹的位置和名称。它只决定 放置方式；每个文件夹内部仍遵循 common/structure.md（业务 → 功能 → 子功能 → 单元），与选择哪种外层框架无关。遵循项目现有的布局（框架脚手架或当前布局）；选择会记录在 .coding-standards-structure 文件中， 因此最多只会询问用户一次。

只需理解一次结构，然后相信记录。 当 .coding-standards-structure 不存在时，理解结构（构建并确认映射，references/structure-map.md），并将 解析出的布局记录在其中。当该文件存在时，遵循其中的内容，不要重新推导或提议重构 ——常规编写 / 审查运行会检查代码是否符合已记录的结构，绝不会重新审视它。只有在用户明确要求 重构或审查结构时，才重新完整理解结构（然后更新记录）——例如“重构这个”“审查结构”“展示结构 树”。常规任务（“添加 X”“审查这个 PR”“这样干净吗？”）不属于此类请求。

简要决策如下：

1. 文件存在于框架项目根目录 → 读取并遵循它（follows: <standard> 目标， 或描述的自定义布局）。无需提问。如果文件不是规范形式——包含注释、hooks: 块或任何规则开关——就在原处将其规范化（只保留 follows: 行 / layout: 主体）， 写回文件，并报告此事。
2. 没有文件，文件夹与某个标准相符 → 使用该标准的参考，并记录下来——写入 follows: <standard> 和完整的 layout: 树，以便后续运行遵循该布局，而无需重新理解。无需提问。
3. 没有文件，且布局为自定义布局 → 使用 AskUserQuestion 向用户询问一次（先推荐结构， “保留当前布局”放在最后），然后写入文件，记录用户的选择。

该文件只记录放置方式——follows: 行和 / 或完整的 layout: 树（实际解析出的结构；项目可以同时包含两者）。其中绝不记录规则开关：始终执行每条规则， 深度导入规则由是否存在 barrel 推导，ST-008 大小 / 文件夹检查则使用固定阈值。block-structure-file-violations.py 会强制执行此要求。

在处理情况 3、单仓库或非规范文件之前，请阅读 references/structure-resolution.md。 其中包含完整机制：单仓库文件的放置位置（子项目根目录，而非仓库根目录）、问题形式、 “保留当前布局”会豁免和不会豁免的内容、自我修复规范化，以及混乱项目的回退方案。

解析出的结构会替代 Step 7b 加载列表中的 references/<framework>/structure.md，并由管道传递给 Worker 1，作为 STRUCTURE。对于“向我展示规则” / 纯问答，请静默解析—— 不要提问，也不要写入文件。

第 5 步 — 选择执行方式（编排流水线或内联）

Write 和 Review 有两种执行方式。先完成第 4 步——结构始终是第一个问题，运行模式是第二个。

触发条件	执行方式
单文件编辑（≤30 行）、单函数重构或规则问答	内联 — 由你自己完成。步骤 6 → 7b。
2 个或更多文件、新功能、差异/PR 审查、--thorough 或 /coding-standards 命令	编排流水线 — 你分派工作者。步骤 6 → 7a。
此宿主中无法使用 Agent 工具（Cursor、Codex、OpenCode）	内联，不受范围影响 — 在路由行中注明。
应用审查结果（“修复这些问题”、“继续修复”/“恢复修复”）	编排流水线，始终使用 MODE: fix。 不询问运行模式。

通过以下两种方式之一做出选择：

A) 通过 /coding-standards 或第 2 步选择器调用，且 Agent 可用 → 按照 references/activation.md 中的确切内容询问运行模式。 “多个 Agent” → 流水线（7a）；“单个 Agent” → 内联（7b）。每个会话最多询问一次；之后沿用答案。

B) 普通消息（无命令） → 根据表格决定。

宣布路由 — 在实质性工作开始前用一行说明

确定模式、框架、结构和执行方式后，输出一行，让用户看到路由：

coding-standards: framework=nextjs · structure=route-colocated (matched) · shape=pipeline (2+ files)

注明执行方式的触发条件（表格中的行，或“用户选择”），并标明结构的确定方式 — (matched)、(file) 或 (asked)。纯规则问答跳过此行；因为没有需要路由的内容。

---

第 6 步 — 使用任务列表跟踪执行过程

进行任何实际工作时 — 编写、编辑、重构或审查 — 都要一开始就立即创建任务列表，也就是刚确定工作范围时：对于第 2 步选择器路径，在用户回答“要审查/编写什么”后立即创建；对于普通消息（“审查此 PR”），在确定文件后立即创建。在第 3–4 步之前创建列表，这样框架检测和确定并记录结构就会作为最先跟踪的事项列在列表中，而不是在列表创建前就已完成的准备工作。任务列表能让标准的应用过程清晰可见 — 用户可以看到每个阶段都已执行，而不必相信它确实发生了。使用宿主的任务列表工具（TodoWrite、TaskCreate/TaskUpdate 等）；仅当宿主没有任务列表工具时才跳过创建，纯规则问答也跳过 — 没有需要跟踪的多步骤工作。

一次性创建完整的工作流，然后根据用户指定的其他目标进行扩展。跟踪用户关心的工作（纳入实际文件/功能名称），始终只保留一个 in_progress 项目，并在开始下一个项目之前完成当前项目。典型的审查列表：确定并记录结构 → 检测框架 → 加载规则 → 审查 → 运行钩子 → 编写报告。典型的编写列表：确定并记录结构 → 检测框架 → 阅读现有代码 → 加载规则 → 起草 → 重写草稿 → 检查规则 → 写入文件。只有当已确定的项目根目录下存在 .coding-standards-structure 时，第一项确定并记录结构才能标记为 completed — 结构通过以下三种方式之一确定：匹配标准、询问并记录，或记录跳过原因（已识别但不受支持的框架，或低于范围阈值）。运行过结构理解 Agent 并不代表完成；磁盘上的文件才算。流水线和 Fix 执行方式会增加工作者/记录阶段 — 参见 orchestrator-pipeline.md。按里程碑推进的修复会在计划获批时为每个里程碑添加一个项目 — 这只是显示镜像；磁盘上的计划文件仍是唯一事实来源。

---

步骤 7a — 流水线分支：协调工作者

你（主 Agent）将担任协调者：协调三名依次执行的工作者，并亲自完成最终 Write，确保钩子恰好在完整代码上触发一次。阅读 references/orchestrator-pipeline.md 并遵循其中的说明——这就是完整协议（工作者名单、 Write/Review/Fix 流程结构、调度循环、验证、重试/回退、摘要）。

即使尚未打开参考文件，以下不变量也始终成立：

• 先理解，再检查。 超过范围阈值，且结构尚未记录在 .coding-standards-structure 中（或用户明确要求重构／审查结构——参见步骤 4）时，先构建并确认结构图（references/structure-map.md），再调度工作者 1；将其作为 STRUCTURE_MAP 传入。如果已有记录且没有此类请求，则跳过结构图，传入记录的结构作为 STRUCTURE——不要重新检查布局。 跨功能结构（重复、嵌套标记错误、功能拆分、主题集群提升）需要通过对照结构图与实际目录树来发现——单个文件的工作者无法发现这些问题。
• 工作者绝不调用 Write/Edit。 他们以 JSON 格式输出代码／发现；只有你可以写入磁盘。
• 依次执行，不并行。 工作者 1（结构）→ 工作者 2（质量）→ 工作者 3（故障）；每位工作者的输出都是下一位工作者的输入。
• 最多重试 2 次。 验证失败两次或 JSON 无法解析时 → 回退到内联处理。

---

步骤 7b — 内联分支：加载参考资料，然后应用

在编写或审查任何代码之前，完整阅读以下内容——每个会话阅读一次，而非每项任务阅读一次：

1. 全部八个 common/ 文件（始终如此）：functions.md、naming.md、objects-and-data.md、 formatting.md、comments.md、error-handling.md、code-principles.md、structure.md。
2. 已确定的结构（来自步骤 4）——structures/<name>.md 变体，或 references/<framework>/structure.md。

请完整阅读，因为判断依据在具体示例中，而非规则名称中。只记得“保持函数简短”会误用 FN-001；示例展示了实际的界限。

然后在各自的适用范围内应用每条规则：common 约束代码内部；已确定的结构约束代码外部（文件位置、文件夹名称、公共 API）。两者看似冲突时，范围划分就是答案——框架入口文件既要保持精简（框架规则），又要确保其导出的函数简短（common 规则）。

---

模式：Write、Review、Fix

编写

编写时也要像审查一样逐条检查规则。大多数 common/ 规则没有写入时钩子，因此不明确列出的规则就不会应用。将这些步骤加入 Step 6 任务列表。Step 1 每个区域只执行一次，而不是每个文件执行一次。

1. 阅读现有代码。 打开最接近新代码落点的 2-3 个文件：优先看目标文件夹中的文件，否则查看同一语言中最相近的功能。记录项目对每种重复操作使用的动词、入口文件导出的内容、一个功能如何划分为单元、有哪些领域错误类型，以及导入的排序方式。规则优先于项目惯例；项目惯例优先于你原本会采用的默认做法。 违反规则的现有文件保持原样；编写任务不会重新整理已有内容。在真正全新的区域中，你要确定用语，因此请确保所写的每个文件用语一致。
2. 加载参考资料（Step 7b）：全部八个 common/ 文件以及已解析的结构。
3. 起草。 先确保行为正确。允许初稿杂乱（FN-012）。
4. 重写草稿。 以第一位读者的视角重新阅读每个文件：拆分你曾因只有 25 行而放过的函数，替换你勉强接受的名称，删除没人需要的参数。
5. 逐条检查规则。 对照 common/ 检查你写的内容，并将每条规则归入已应用、已满足或不适用（附理由）之一。对于在此步骤之前未考虑过的规则，重新阅读参考资料。在回复中报告各类别，不要写入文件。
6. 立即修复发现的问题。 违规之处要么修复后提交，要么不提交。绝不要用 TODO 搭配违规内容。

默认不写注释（comments.md）。用名称和代码结构表达意图。只有当一句话传达了代码无法表达的内容——约束、理由、外部参考或容易出错之处——才值得写入文件。绝不叙述代码，绝不叙述你的修改，也绝不在文件中留下对话内容：不要写 as requested、I think、we could also、未跟踪的 TODO、表情符号或 Note: 前缀。如果某个想法应该放在给用户的回复中，就写在那里，并保持文件整洁。

单独的模型会在本轮结束前评判本轮所写的注释（hooks/judge-comments.py），因此，不值得保留的注释会作为需要修复的问题退回，而不是作为可忽略的备注。第一次就写对，评判器就会保持沉默——每个修改过代码的轮次只需一次简短的模型调用，而文件没有新增注释的轮次则完全不需要调用。

始终通过 Write / Edit / MultiEdit 工具编写和修改代码——绝不要使用 Shell 重定向（> file、>>、tee、sed -i、cat <<EOF > file）。执行钩子只会在 Write/Edit/MultiEdit 上触发；通过 Shell 写入文件会悄无声息地绕过所有钩子。这是执行边界上的真实漏洞，而本指令是唯一能堵住 Shell 写入漏洞的东西——因此务必遵守。如果某个工具确实必须在 Write 路径之外生成源文件，请对生成的文件运行 python3 <skill-dir>/hooks/review-files.py <file>，并修复报告的问题。

审查

系统地逐条检查规则——不要随意发挥。确定审查范围后、开始审查前，立即将清单加入 Step 6；编号步骤与清单对应，第 0 步是清单的第一项。 0. 解析并记录结构 — 第一个任务项，只有在 .coding-standards-structure 存在时才算完成。 超过范围阈值时，且仅当结构尚未记录时：如果 .coding-standards-structure 已记录结构，且用户没有要求重构／审查结构，则跳过此步骤 — 遵循已记录的结构并据此审查代码；不要重新审视布局。否则，基于整个目录树构建结构映射（references/structure-map.md），与用户确认一次，将其保存到 .coding-standards/structure-map.md，并在 .coding-standards-structure 中记录已解析的布局。将映射作为 STRUCTURE_MAP 交给结构工作器：跨功能发现（重复、同级项嵌套错误、功能拆分、主题集群提升）是相对于此映射的差异，逐文件检查无法发现这些问题。低于阈值时跳过 — 说明未运行跨功能结构检查。

1. 确定范围并解析结构。 列出差异中的每个文件；识别其框架（步骤 3）并解析结构（步骤 4）。
2. 加载参考资料。 所有 common/ 文件，以及差异中每个框架对应的已解析结构。
3. 判断审查 — 检查规则 regex/AST 无法捕获的问题（FN-001 长度细节、FN-009 CQS、OD-003 Demeter、EH-002 边界、CM-* 注释正文规则、structure.md 规则）。对每条规则，报告 PASS、一条发现（格式为 file.tsx:42 — <rule> — <what's wrong>），或 SKIPPED — <why it doesn't apply>。
4. 运行钩子作为代码检查器（确定性检查，最后运行 — 不要跳过）。block-*.py 钩子仅在 Write/Edit 时触发，因此审查时必须显式调用：

   python3 <skill-dir>/hooks/review-files.py <file> [<file> ...]
   # diff:   git diff --name-only | python3 <skill-dir>/hooks/review-files.py --stdin
   # pipeline: add --json and parse per file
   

   它会应用相同的写入时契约（any、匈牙利命名法、4+/5+ 个参数、吞掉错误、杂物抽屉路径、深层导入、TS/Python AST 检查），并跳过排除的文件。review-files.py 会自行选择能够加载 TS/JS 语法的解释器（如果启动它的 python3 缺少相关语法，则使用随附的 venv）；如果没有可用解释器，它会明确提示这一缺口 — 绝不会悄悄地将 TS 文件报告为通过。**它返回的每条发现都是必须修复的违规：**发现的存在是确定的，绝不重新争议（any 就是 any）。对于 ST-008 声明数检查，补救方式由审查者判断 — 进行合理的拆分，或者在文件确实只承担一项连贯职责、代理却错误计数时，记录豁免（.coding-standards-ignore + 原因，日志状态为 accepted）。造成代码分散或复制同级文件机制的拆分，本身就是 ST-008 + DP-007 违规，而非修复。
5. 合并、撰写报告并总结。 将判断审查与代码检查器的发现合并为一个列表，按文件再按规则代码排序。不设严重性等级 — 每条发现都是必须修复的违规。 发现唯一可不修复的处理方式只能在修复阶段进行：accepted（审查者判断此处不构成违规 — 必须说明原因）或 deferred（确有违规，但暂不处理）。审查阶段的判断是二选一：违反规则（记录）或未违反（通过，而非“建议考虑”）。根据 references/review-report.md 将合并结果保存到报告文件（.coding-standards/reviews/<timestamp>.md，已加入 gitignore），并告知用户文件路径 — 每次审查都必须写入报告，包括内联审查。报告中的 Structure baseline: 字段为必填项，须注明已记录的 .coding-standards-structure（或说明 NOT RECORDED 并给出原因）— 参见 references/review-report.md。超过范围阈值（在 orchestrator-pipeline.md → 修复模式中定义一次）时，将聊天输出精简为 review-report.md 规定的格式；报告文件始终包含所有内容。
6. 验证结构基线，然后绝不悄悄跳过规则。 写完报告后，运行 python3 <skill-dir>/hooks/check-review-report.py <report.md>（在 monorepo 中传入 --root <sub-project>）。退出码 2 表示报告声明了结构基线，但对应的 .coding-standards-structure 不存在 — 结构步骤（步骤 4／步骤 0）被跳过：解析并记录结构，然后重写报告，之后再报告完成。退出码 1 表示已声明跳过 — 说明原因。这是任务清单项的兜底检查：如果基线从未写入，报告就不能声称审查已完成。如果某条规则未检查，也要说明 — 隐瞒缺口的审查比坦承范围有限的审查更糟。

修复

由“修复这些发现”／“应用评审意见”／评审后立即提出的修复请求触发；也可通过“继续修复”／“恢复修复”接续尚未完成的里程碑计划。修复模式始终作为编排流水线运行（MODE: fix）——它本质上涉及多个文件：为每个文件分派一个修复 Agent，并通过完整性台账跟踪，确保不会有任何修复悄然半途而废。不要提供“单个 Agent”选项；如果 Agent 不可用，请运行文档中说明的顺序批处理回退方案，并明确说明。

每项发现最终都标记为 fixed（违规已移除）、accepted（判定为不构成违规——必须说明原因）或 deferred（确实违规，但尚未修复——属于未解决违规）。存在未解决违规的运行结果应报告为 done-with-open-breaches，绝不能报告为 done，除非用户已解决这些违规——参见 references/fix-plan.md。

输入是最新的 .coding-standards/reviews/<ts>.md；如果不存在，请先运行 Review。其他所有内容——台账、按文件分派、范围阈值，以及适用于大型修复的里程碑驱动计划文件（references/fix-plan.md）——都位于 references/orchestrator-pipeline.md 的“Fix mode”部分。

---

按需查找规则

规则按问题类型组织（函数、命名、对象／数据、格式、注释、错误处理、原则、结构），而非按语言组织。完整的“问题→文件”索引位于 references/rule-index.md——查询“FN-005 是什么意思？”或不确定某个问题归哪个参考文件时，请使用该索引。实际工作中，第 7 步已经会加载所有内容，因此该索引仅用于有针对性的查询。

---

发生冲突时——更简单且正确的设计胜出

当两种设计都正确，但在其他原则上彼此冲突时，**DP-006（KISS）**负责打破平局：更简单的设计胜出，即使它稍微偏离了 DRY 或其他规则。KISS 是平局时的裁决原则，而非王牌——它绝不能凌驾于正确性、真实需求或 SOLID 之上。你不能以此为由，跳过交给你的每个变体都要实现的类（OD-002）、吞掉错误，或发布静默回退方案。为了满足规则而添加某种模式（Strategy、Visitor，或第五层间接层）？停下——简单的版本通常才是正确的。为了逃避结构要求，把上帝文件或重复的 switch 辩称为“简单”？也请停下——那并非更简单，只是更小。

---

此技能不涵盖的内容

• 性能调优——请使用分析器；默认情况下，干净的代码已经足够快。
• 安全评审——请使用专门的安全技能（例如 security-review）。干净代码评审能发现某些类别的错误，但并非安全审计。
• 测试设计——测试也遵循相同的干净代码规则，但 TDD／BDD／变异测试策略不在范围内。
• UI／UX 视觉评审——这是独立领域（web-design-guidelines、design-taste-frontend）。这些框架涵盖的是代码组织，而非视觉设计。

如果用户提出上述任何一项，请说明此技能不涵盖该内容，并指引他们使用相应工具。