轨道 · 写下来的字

AI Coding软件工程最佳实践手册

2026.10.21

AI 辅助软件工程最佳实践手册

日期：2026-10-21｜适用：个人开发、小团队、AI Agent 协作、需长期维护的软件项目

目标：把 AI 从”按提示生成代码的工具”变成受规范约束、可验证、可追溯的软件工程协作者。质量优先于生成速度；任何未经验证的输出都不视为完成。

范围声明：本手册是工程实践指引，不是合规审计材料，也不替代组织既有的安全、法务与质量体系。涉及监管、客户数据或资金的功能，以所在组织的制度为准。

维护：由使用本手册的项目自行维护。修订方式：提出改动 → 说明触发的问题（真实事故或反复出现的摩擦）→ 记录到版本历史 → 同步更新受影响的模板与清单。规则若长期无人遵守或总被绕过，应修改规则而不是增加规则。

编辑原则：同一事实只写一次。正文写”为什么”，模板写”填什么”，提示词写”怎么说”。发现第二处相同表述时，改为指向第一处。

目录

0. 定位、适用边界与使用方式
1. 风险分级与流程裁剪
2. AI 软件开发生命周期
3. SDD：规格作为活的事实来源
4. 仓库结构与文档职责
5. AGENTS.md / CLAUDE.md 与规则分层
6. 架构设计与代码组织
7. AI 代理的权限、上下文与协作
8. AI 协作反模式
9. 数据库设计标准
10. API、事件与分布式可靠性
11. 安全、隐私与供应链
12. 错误处理、日志与可观测性
13. 测试策略与质量门禁
14. 文档同步规则
15. Git 与变更管理
16. 代码审查清单
17. 技术栈配置
18. Definition of Done
19. 最小落地路线与度量
20. 最终执行原则

附录 A：最小模板（spec / plan / tasks / verification / ADR / checklist / progress / AGENTS） 附录 B：常用工作流提示词 附录 C：案例：桌面应用（下载器类）的实践 附录 D：自动化与可复用能力库（设想） 附录 E：术语表

0. 定位、适用边界与使用方式

0.1 定位

本手册建立一套通用工程内核 + 项目类型配置 + 技术栈规则包。Web、后端、桌面应用、CLI、Rust/GPUI 项目复用同一生命周期，但使用不同的检查命令和架构约束。它不要求所有项目采用同一技术栈，也不要求所有变更走同样重的流程（见第 1 章）。

0.2 核心原则

1. 先澄清，再设计，再编码。 不因提示词含糊就自行补全关键业务规则。
2. 规格是活的事实来源。 需求、架构、接口、数据模型、测试与实现必须保持一致。
3. 小步交付，每步验证。 每次变更范围应小到能够理解、测试和回滚。
4. AI 提议，工具验证。 编译器、测试、静态分析、集成测试和运行结果优先于 AI 自我判断。
5. 人类负责高风险决策。 数据迁移、认证授权、删除数据、费用、发布、密钥和破坏性操作必须设置审批边界。
6. 可追溯。 每项重要变更都能追溯到需求、设计决策、任务、测试和 Git diff。
7. 理解债与代码债同等严重。 不能合并无法向他人解释的代码，即使它通过了测试。
8. 不过度工程化。 以当前需求为基础，避免为尚未证实的未来需求预建复杂抽象。
9. 默认安全、可恢复。 对失败、重试、取消、并发、部分成功和崩溃恢复做显式设计。

0.3 怎么用这份手册

1. 风险分级与流程裁剪

同一套流程不应不加区分地套用于所有变更。按风险选择流程强度，既避免小改动被流程拖垮，也避免高风险改动被轻率放行。

1.1 三级定义

判定规则：

• 拿不准时按更高一级处理。
• AI 可以建议等级，但 L2 的认定与审批由人类负责。
• 任务只要触及 L2 特征（例如顺带改了数据库结构），整体升级为 L2。
• 能力风险是第二个维度：同一等级下，若变更涉及 AI 可靠性明显偏低的领域（并发原语、unsafe、加密实现、FFI、复杂算法、许可敏感代码），按更高一级处理，并优先选择”人类主导设计、AI 辅助实现”。

1.2 各等级的最低要求

1.3 检查手段分级

规则不写检查手段，落地就只能靠自觉。本手册要求每条硬性规则尽量落在前两类：

约束：Judgment 类规则必须写进审查清单，否则等于不存在；Review 类规则必须能转成可回答的是/否问题，否则等于口号。

2. AI 软件开发生命周期

2.1 阶段与退出条件

阶段 0 项目识别 ─▶ 阶段 1 需求与规格 ─▶ 阶段 2 架构与设计 ─▶ 阶段 3 任务拆分
     ─▶ 阶段 4 实现 ─▶ 阶段 5 验证与审查 ─▶ 阶段 6 文档同步 ─▶ 阶段 7 提交、发布与复盘

未达到退出条件，不进入下一阶段。深度按第 1 章裁剪；可以简化文档，但不能跳过验证。

2.2 阶段 0：项目识别与现状盘点

AI 首先检查，而不是立即改代码：项目类型与工具链、目录结构与入口、现有测试与 CI、项目约定文件（AGENTS.md、.ai/、docs/）、Git 状态与未提交变更、可复用模块与技术债。

禁止：未检查 Git 状态就覆盖文件；未理解现有架构就大规模重构；把用户未提交的变更当作自己的工作去修改。

输出 Project Discovery 摘要：项目概况、已发现约束、可复用资产、风险、建议的下一步。

2.3 阶段 1：需求与规格

目标是固化”要做什么、不做什么、怎么算做对”。字段与结构见 A.1，此处只讲判断：

• 验收标准必须可观察、可执行；“体验良好”不是标准，要写成 Given/When/Then。
• 目标与非目标同等重要。写不出非目标，说明范围还没想清。
• 关键假设单列，不能伪装成已确认需求。涉及数据语义、权限、费用、兼容性或不可逆操作时，先问再写。
• 不影响核心正确性的细节，AI 可以提默认值并标注”默认值待确认”。

陷阱：AI 倾向于顺着你的前提往下展开。若前提有误（例如”在已有表上加一列即可”但实际需要分表），错误会被完整固化进规格、设计、代码和测试。因此阶段 1 必须显式质疑一次：这个方案的前提成立吗？有没有更简单的路径？

2.4 阶段 2：架构与设计

要拍板的是三件事：边界（模块职责与依赖方向）、契约（数据模型与接口）、失败方式（并发、幂等、回滚、可观测性）。字段见 A.2。

重要或难逆的技术决策记为 ADR（A.5）。不要为每个小细节创建 ADR，只记录会显著影响未来维护、兼容性、成本或协作的决策。

2.5 阶段 3：任务拆分

每个任务必须有 ID、范围、依赖、验收标准、验证命令、风险等级与回滚方式。字段见 A.3。

标准是：任务可独立验证。若某个任务说不清”怎么算做完”，说明它还不是任务，是阶段。

若实现中发现计划不成立，先更新计划和规格再继续，不要悄悄偏离。

2.6 阶段 4：实现

每次只处理一个有边界的任务：

1. 读相关规格、架构、代码和测试。
2. 说明将修改什么、为什么、影响哪些模块。
3. 先写或更新测试（Bug 修复先写出会失败的复现测试），再实现。
4. 最小必要 diff，不夹带无关格式化和重构。
5. 先跑针对性测试，再跑更广泛的验证。
6. 更新规格、文档、变更记录和任务状态。
7. 检查 diff、敏感信息、依赖变更和兼容性。
8. 验证通过后才建议提交。

AI 不应一次性生成大批互相依赖、尚未编译的代码。探索性原型必须标记为 prototype / spike，不能把探索代码直接视为生产实现。

提交前自问：这段代码我能讲清为什么这样写吗？讲不清的部分，要么让 AI 解释到能复述，要么重写（见第 8 章”代码缝合怪”）。

2.7 阶段 5：验证与审查

验证层次：格式化与静态检查 → 单元测试 → 集成测试 → 契约测试 → 关键路径 E2E → 安全/依赖/秘密扫描 → 性能与资源（L2 或指标明确时）→ 构建与目标平台运行 → 文档一致性。

必须报告实际执行过的命令与结果，不能把”代码看起来正确""测试应该会通过”写成验证通过。环境无法执行时标为”未验证”并说明原因。

证据形态：结论必须附可复核的原始证据——命令输出片段、测试通过/失败计数、CI 运行链接或产物路径。转述不算证据。这条对 AI 尤其有效：它让”声称跑过”的成本高于”真的跑一遍”。

2.8 阶段 6：文档同步

按第 14 章的影响分析表执行。此阶段不可省略——即使结论是”无需更新”，也要留下判断记录。文档与实现不一致的代价，通常在一个月后由别人（或未来的自己）支付。

2.9 阶段 7：提交、发布与复盘

提交前确认：需求满足、测试通过、文档同步、无意外文件、无密钥、无临时产物、迁移可执行、回滚可行。

提交信息采用 Conventional Commits（feat / fix / refactor / perf / test / docs / build / ci / chore / revert），细节见第 15 章。

不允许 AI 未经明确授权推送、发布、删除远端分支、执行生产迁移或做不可逆操作。 本地 commit 是否自动执行由项目策略配置，默认先展示验证结果与拟提交摘要。

发布后复盘三问：哪些问题本应更早发现？哪条规则没起作用，是规则错还是执行不到位？该新增规则，还是该把它变成机器门禁？

3. SDD：规格作为活的事实来源

采用轻量 Spec-Driven Development，不把流程工具本身当目标。

3.1 位置

SDD 不引入第 2 章之外的新流程，它规定的是每个阶段留下什么产物：Constitution 在上（长期原则），Specification 次之（本次做什么），然后依次产出 Architecture / Plan、Tasks，实现与验证都回指对应文档。各阶段的划分与退出条件见 2.1；文档的分工与存放见第 4 章。

一句话：第 2 章管”按什么顺序做”，SDD 管”每步留下什么证据”。

3.2 不一致时怎么办

规格不是凌驾于运行代码之上的”绝对真相”：如果代码、测试和规格不一致，必须调查并明确修正哪一方。禁止只改文档掩盖实现缺陷，也禁止只改代码而不更新规格。

判定顺序：先看测试是否表达了预期行为 → 再看规格是否遗漏该行为 → 最后判断是代码错还是规格错。修哪一方，在提交信息里写明。

3.3 规格何时必须回退修订

实现阶段出现下列任一信号，停止在代码里打补丁，回到阶段 1 修订规格：

• 同一功能出现 3 次以上规格未覆盖的情形。
• 验收标准无法写成可观察、可执行的断言。
• 反复出现”这个分支规格没说，先这样写”。
• 任务拆分时发现某个任务无法独立验收。
• 需要修改公开契约（API / 事件 / schema / 配置格式）才能满足规格。

修订规格的代价是一小时；让偏离在代码里积累三周的代价是一个模块。

4. 仓库结构与文档职责

4.1 目录结构

project/
├── README.md / AGENTS.md / CLAUDE.md / CHANGELOG.md / CONTRIBUTING.md
├── .gitignore / .editorconfig
├── .ai/
│   ├── constitution.md   # 工程宪章：长期原则与质量门槛
│   ├── workflows/        # 工作流提示词（见附录 B）
│   ├── checklists/       # 可勾选清单（见 A.6）
│   ├── templates/        # 模板（见附录 A）
│   ├── knowledge/        # 项目事实性背景：领域术语、外部系统约束、历史坑
│   └── project.yaml      # 项目类型、命令、门禁与权限配置
├── docs/                 # 稳定态文档：当前系统"是什么样"
│   ├── architecture/  adr/  api/  database/  operations/  testing/  releases/
├── specs/                # 变更过程文档：某次变更"要做什么、怎么做"
│   └── <feature>/  spec.md  plan.md  tasks.md  verification.md  progress.md
├── src/  tests/  scripts/
└── .github/workflows/

按项目规模裁剪。小型 CLI 不必为了结构而创建空目录，但应保留适用的规格、测试和运行说明。

.ai/knowledge/ 存放无法从代码推断的事实：领域术语的确切含义、外部系统的历史行为、踩过的坑、为什么不采用某个显而易见方案。这些内容只留在聊天记录里，下一次会话必然重复踩坑。

4.2 文档职责与 specs/ / docs/ 边界

两个目录的分工（避免双份事实来源）：

• specs/<feature>/ 记录一次变更的意图、计划与验证过程，带时间属性，完成后保留为历史（状态：Draft / Accepted / Implemented / Superseded）。
• docs/ 记录当前生效的系统事实（架构、接口、数据库、运维）。
• 功能完成后，把其中的稳定结论合并进 docs/；业务需求若需长期维护，放在 docs/ 而非 specs/。
• verification.md 记某次变更的实际验证结果；docs/testing/ 只写测试策略与运行方法。
• 同一内容不要在两处各维护一份。

4.3 哪些内容应该提交到 Git？

• 通常提交：docs/、specs/、AGENTS.md、CLAUDE.md、架构图、ADR、数据库迁移、测试、脚本、CI 配置、README、变更日志。
• 通常不提交：密钥、令牌、个人临时笔记、机器相关缓存、构建产物、运行日志、真实用户数据、未经清洗的生产转储、可再生的大文件。生成文件是否提交，以可再生性、审查价值和团队约定为准。

5. AGENTS.md / CLAUDE.md 与规则分层

5.1 四层规则

规则应分层，避免复制粘贴后逐渐冲突：

1. 通用宪章：适用于所有项目的安全、验证、文档、Git 规则。
2. 项目级规则：架构、模块边界、命名、测试命令和业务限制。
3. 目录/模块级规则：仅对特定目录生效的细节。
4. 任务级说明：本次目标、范围、验收标准和允许的操作。

AGENTS.md 作为通用代理指引入口；CLAUDE.md 用于对应工具的专属入口。两者内容相同时，应让其中一个引用另一个（例如 CLAUDE.md 中用 @AGENTS.md 导入），或由模板生成，避免规则漂移。其他工具（Cursor、Copilot、Gemini 等）的规则文件同理，统一指向同一份事实来源。具体加载与导入语法以所用工具当前版本的文档为准。

5.2 保持入口文件简短

入口文件越长，代理对其中每条规则的遵守率通常越低，且容易与详细文档冲突。建议：

• 入口文件只放：项目概述、构建/测试/lint 命令、目录约定、少量硬性禁令、指向详细文档的链接。
• 流程细节放进 .ai/constitution.md 与 .ai/workflows/，按需引用。
• 每条规则应可检查、可执行；无法验证的空泛口号不写。
• 单条规则尽量能用”是/否”回答，避免”尽量""适当""合理地”这类无法判定的措辞。

模板见 A.8。

6. 架构设计与代码组织

6.1 分层与依赖方向

Presentation / UI
        │ 依赖
        ▼
Application / Use Cases
        │ 依赖
        ▼
Domain / Business Rules
        ▲ 实现（Infrastructure 依赖 Domain 定义的端口）
        │
Infrastructure（数据库、HTTP、文件系统、外部服务适配器）

读法：▼ 表示”上层依赖下层”，▲ 表示”下层实现上层声明的抽象，依赖方向指向 Domain”。Domain 不依赖任何外层；Infrastructure 依赖 Domain 的端口接口，反之不成立。

具体依赖规则依项目类型调整，但核心业务规则不应被 UI、数据库驱动或外部服务细节绑死。

6.2 架构检查点

• 每个模块有清晰职责和公开接口。
• 依赖方向单向、可解释；避免循环依赖。
• Domain 不直接依赖具体数据库、UI 框架或外部 API。
• 外部系统通过适配器/接口隔离。
• 不为简单需求引入不必要的微服务、消息总线或抽象层。
• 跨模块调用使用稳定契约；共享状态有明确所有权和同步规则。
• 重要状态变化使用显式状态机，避免到处修改多个布尔值。
• 异步任务明确取消、超时、重试、幂等和生命周期。
• 高风险操作设计审计、补偿、恢复和回滚路径。

6.3 代码规模阈值的正确使用

可将”业务文件约 200 行、函数约 50 行、圈复杂度约 10、嵌套不超过 3 层”作为触发审查的软阈值，不是机械的绝对规则。短代码不一定清晰，拆分也可能造成过度碎片化。超限时要求说明原因或给出重构计划，而不是为了数字制造更多文件。

该阈值对 AI 生成代码有额外意义：AI 容易在单个文件里堆叠职责。文件显著超限时，优先怀疑”职责没切开”，而不是”需要拆文件”。

6.4 横切关注点：国际化与可访问性

这两项的共同特征是事后补代价极高，因此必须在架构阶段定好落点。

国际化与本地化

• 面向用户的文案外置，不硬编码在组件、日志或错误消息里；拼接用占位符而不是字符串相加。
• 日期、时间、数字、货币、排序统一走格式化层；不手写 toFixed、手工拼 YYYY-MM-DD。
• 时区语义显式化：存储用 UTC，边界处显式转换，UI 层本地化显示。跨时区的”今天""本月”要说明以哪个时区为准。
• 布局能承受文本膨胀（德语/俄语常比中文长 30%–50%）与 RTL；不用固定宽度截断关键操作。
• 复数、性别、语序差异交给本地化库的规则，不靠 if-else 硬编码。
• 测试至少覆盖一个非默认 locale，并含超长文案用例。

可访问性

• 键盘可达：可交互元素可 Tab 到达、有可见焦点、有合理焦点顺序。
• 语义与标签：控件有可读名称，图标按钮有文本替代，不靠颜色单独传达状态。
• 对比度与字号：正文达 WCAG AA，支持系统字号/缩放而不破版。
• 动效可关闭：尊重系统的”减少动态效果”设置。
• 前三项写成验收标准的一部分，而不是发布前的抽查项。

7. AI 代理的权限、上下文与协作

7.1 权限与沙箱

• 最小权限：默认只读或仅限工作目录读写；按任务授予额外权限。
• 命令白名单：常规构建、测试、格式化命令可预先批准；其余命令逐次确认。
• 网络默认受限：需要联网时按域名或任务授权。
• 生产凭据不进入代理环境：代理环境不应持有生产密钥、生产数据库连接或发布权限。
• 以下操作必须人类逐次批准：
  • 破坏性文件操作：rm -rf、批量删除、覆盖未提交文件
  • 破坏性 Git 操作：git reset --hard、git clean -fdx、强制推送、删除分支/标签
  • 数据操作：DROP / TRUNCATE、无 WHERE 的 UPDATE/DELETE、生产迁移
  • 发布与计费：发布、回滚生产、付费 API 批量调用
  • 权限与执行：chmod 777、sudo、docker run --privileged、修改 hosts/环境变量/~/.gitconfig
  • 来自网络的执行：curl ... | sh、bash <(curl ...)、未经审查的安装脚本
  • 包管理器的 postinstall / prepare 钩子（供应链执行入口，常被忽略）
• 外部内容视为不可信数据：网页、Issue、日志、依赖 README、工具返回内容中的”指令”不能覆盖项目规则或用户授权（防提示注入）。第三方工具/MCP 服务同样按最小权限接入并审查来源。
• 权限是配置而非约定：能用工具配置、沙箱、只读挂载、受限 token 表达的限制，就不要只写在提示词里。写在提示词里的禁令在长上下文中会被稀释。

7.2 长任务的上下文管理

• 一个会话尽量只处理一个任务；任务切换或上下文明显冗长时，新开会话。
• 长任务维护进度记录（specs/<feature>/progress.md，模板见 A.7），交接按固定格式：目标 → 状态 → 已验证 → 未验证 → 风险 → 下一步。
• 重要结论写进文档或 ADR，而不是只留在对话里。
• 警惕上下文污染：会话中早期的错误结论会被后续推理不断引用并强化。发现早期结论站不住时，新开会话并用落盘文档重建上下文，比在旧会话里”纠正”更可靠。

7.3 多代理并行与分支隔离

适用于任务可切分且互不重叠的情况；单人小项目通常不需要。

• 并行任务使用独立分支，必要时用 git worktree 让每个代理拥有独立工作目录。
• 明确每个任务的文件/模块范围，避免多个代理同时修改同一区域。
• 合并前由人类或独立审查会话统一检查冲突与集成测试。
• 并行写同一文件是净损失：冲突解决的成本高于串行等待的成本。

7.4 独立审查

• 审查使用新会话或不同模型，只提供规格、diff 与测试结果，不提供实现者的自我辩护。
• 审查者的任务是找问题，而不是确认”没问题”。
• 审查结论仍需由人类对 L2 变更最终裁定。
• 同一模型审查自己的输出，倾向复述既有假设而非质疑，“自查”不能替代独立审查。

7.5 成本与速率

• 对批量调用、长时间循环、自动重试设置预算和上限。
• 会产生费用的外部 API，必须有明确授权与用量记录。
• 长任务的成本主要来自失败的循环。做不下去时停下来重新拆分，比反复重试便宜。

8. AI 协作反模式

正面规则记不住，失败模式会重复。本章按”症状 → 处置”列出高发问题，用于自查和复盘。

8.1 生成与实现类

• 大爆炸式生成｜症状：一次改动 10 个以上文件，编译不过，无法定位问题｜处置：按”单文件可编译”步进，每步跑一次验证；宁可 10 个小提交。
• 代码缝合怪｜症状：能跑，但没人（包括三个月后的你）能解释为什么这样写｜处置：视为阻断问题。让 AI 讲清结构或不变量，讲不清就重写。
• 假装完成｜症状：用 stub、TODO、unimplemented!()、空分支冒充实现，报告里写”已完成”｜处置：提交前搜索 TODO|FIXME|unimplemented 等标记，逐个确认是否有意保留。
• 生造 API 与配置项｜症状：调用了不存在的函数、不存在的配置键、听起来很合理的库参数｜处置：以编译器、类型检查、文档或实际运行结果为准。
• 注释与文档膨胀｜症状：每行配一段解释，注释复述代码而不说约束｜处置：注释只写”为什么""有什么陷阱""为什么不用另一种写法”。
• 顺着错误前提写｜症状：需求本身有误，规格、设计、代码、测试层层继承了这个错误｜处置：阶段 1 显式质疑前提（见 2.3）。
• 过度抽象｜症状：一个功能引出三层接口、两个工厂、一个泛型容器｜处置：第二次重复出现再抽象；先问”有没有第二个真实调用方”。

8.2 验证类

• 自证循环｜症状：AI 写实现、写测试、跑测试、宣布通过，而测试只是把实现抄了一遍｜处置：测试与实现分开生成；先写会失败的测试；核心逻辑用变异测试抽查（见 13.2）。
• 重试到绿｜症状：测试一直不过，几轮之后”通过了”，实际是断言被放宽或删除｜处置：修改既有断言必须在提交信息里说明理由；禁止删除断言而不删除对应功能。
• mock 泛滥｜症状：所有依赖都被 mock，测试全绿，集成全挂｜处置：核心边界必须有真实或高保真替代（临时数据库、容器化服务、本地 HTTP 服务器）。
• 断言缺位｜症状：测试只验证”没抛异常”｜处置：每个测试至少有一个对可观察结果的断言。
• 声称跑过｜症状：报告”已验证”，但只有转述，没有原始输出｜处置：要求附原始输出片段或 CI 链接（见 2.7）；无证据即视为未验证。
• 覆盖率刷分｜症状：覆盖率 85%，但高风险分支一个没测｜处置：看路径覆盖而非行覆盖；用”这行写错了哪个测试会红”来检验。

8.3 协作与上下文类

• 上下文污染｜症状：会话越久，AI 越坚持早期的错误结论｜处置：新开会话，用落盘文档重建上下文（见 7.2）。
• 多任务混会话｜症状：一个会话里穿插三个需求，改动互相污染｜处置：一任务一会话一分支。
• 机密进提示词｜症状：把真实日志、连接串、客户数据整段贴给模型｜处置：先脱敏再问；不确定是否敏感时按敏感处理（见 11.3）。
• 无边界并行｜症状：两个代理同时改同一批文件，合并时冲突成灾｜处置：明确文件归属或串行执行（见 7.3）。
• 过度授权｜症状：为省事给了全盘写权限和免确认，一次误操作覆盖工作区｜处置：能写配置就不写提示词（见 7.1）。
• 规则通胀｜症状：每次出问题就加一条规则，规则表越来越长，遵守率越来越低｜处置：先判断是规则错、执行不到位，还是该变成机器门禁（见 19.1 第 4 周）。

8.4 怎么用这一章

• 提交前自查：对照 8.1、8.2 各扫一遍，大多数问题在这一步能拦住。
• 独立审查：审查提示词里明确要求检查本章列出的反模式（B.6）。
• 事故复盘：定位到具体反模式，再回对应章节补规则或补门禁——不要只写”下次注意”。

9. 数据库设计标准

9.1 命名与结构

• 表名：小写、复数、snake_case；字段名：snake_case。接入既有数据库时，与既有风格一致优先于本约定——一个库内混用两种命名风格的代价高于任何单一约定。
• 主键统一用 id；ID 类型根据规模与分布式需求选 UUID/ULID/自增，理由记 ADR。
• 时间字段通常含 created_at、updated_at；软删除用 deleted_at。
• 时间戳统一语义和时区，跨系统通常以 UTC 存储、展示时转换。
• 金额用定点数或最小货币单位整数，避免二进制浮点误差；选型需与货币精度和数据库能力一致。
• 布尔字段用肯定式命名（is_active 而非 is_not_deleted），避免双重否定。

9.2 约束必须落在数据库层

显式考虑 NOT NULL、UNIQUE、FOREIGN KEY、CHECK、DEFAULT、索引和删除/更新策略。应用层校验用于友好报错，不能替代数据库一致性约束。

默认遵循 3NF。确需反规范化时，记录：为什么需要（测量到的性能/查询需求）；哪个字段是权威数据源；同步与一致性策略；修复/重建方式；可能产生的异常状态。

9.3 迁移规范

• 所有 schema 变更使用版本化迁移并纳入 Git；可审查、可在测试数据库重复验证。
• 评估锁表、数据量、兼容窗口、回滚与备份策略。
• 高风险线上变更采用 expand → migrate → contract 的渐进方式。
• 生产迁移需要审批与备份/恢复方案，不由 AI 自行执行。
• 不直接编辑已应用的历史迁移；新增后续迁移修正。
• 考虑旧版本代码仍在运行的窗口期：新列可空或带默认值，重命名走”新增 + 双写 + 切换 + 删除”。

9.4 查询与事务

• 避免 N+1；根据场景采用批量查询、JOIN、预加载。
• 列表 API 必须分页；设置合理默认和上限。
• 多步骤写操作定义事务边界；事务内避免网络请求和长耗时操作。
• 通过唯一约束、幂等键、状态条件更新处理重复请求。
• 索引要有依据，并通过执行计划/实际测量验证，不凭感觉堆索引。

10. API、事件与分布式可靠性

10.1 契约

• 契约明确字段、类型、必填、校验、错误码、分页、排序、兼容策略。
• 统一错误结构，例如 code、message、trace_id；对外消息不泄漏内部堆栈或敏感信息。
• 错误码与 HTTP 状态的映射版本化且集中定义，不能让客户端靠匹配错误信息字符串判断分支。
• 兼容策略显式化：新增字段可兼容，删除/改名/收紧校验属破坏性变更，需版本升级或过渡期。

10.2 可靠性与失败处理

• 对外部调用设置超时、有限重试、退避与抖动、熔断/限流（按需要）。
• 仅对可安全重试的操作自动重试；非幂等操作必须有幂等键或业务去重。
• 不承诺真正的”恰好一次执行”；常见设计是至少一次投递 + 幂等消费 + 状态约束 + 对账/补偿。
• 消息处理区分业务失败、可重试失败和永久失败；设计死信/人工处理路径。
• 事件契约版本化，明确顺序性、重复投递、迟到事件和兼容规则。
• 补偿与对账要有可执行入口（脚本或接口），不能只写在设计文档里。

11. 安全、隐私与供应链

11.1 基础安全

• 不把密钥、Token、密码、生产连接串写入代码、文档、日志或测试快照。
• 使用环境变量或 Secret Manager；仓库只保留 .env.example。
• 所有外部输入做类型、范围、长度、格式和权限校验。
• 使用参数化 SQL；对输出按上下文编码，避免注入。
• 认证与授权分别独立设计；默认拒绝，按最小权限授予。
• 日志不得记录密码、完整令牌、私密内容或不必要的个人数据；建立脱敏规则。
• 文件上传、路径操作、反序列化、命令执行、URL 抓取都需要威胁建模。
• 高风险功能用 feature flag、权限校验、审计日志和回滚开关保护。

11.2 AI 带来的供应链风险

• 依赖幻觉：AI 可能编造不存在的包名，或推荐名称相近的恶意包（typosquatting）。新增依赖必须由人核实：来源是否为官方注册表、维护活跃度、版本、许可证、是否真有必要、是否有 postinstall 脚本。
• 依赖升级审查变更日志与锁文件 diff；持续运行漏洞与许可证扫描。
• 锁文件变更视为敏感 diff：它决定实际构建出什么，审查时不能只看 package.json / Cargo.toml。
• 不允许为通过检查而降低安全配置（关闭校验、放宽权限、禁用扫描）。

11.3 数据外发与许可

• 明确哪些数据不得发送给外部模型或第三方工具：密钥、个人敏感数据、受保密约束的代码与客户数据（以组织与合规要求为准）。
• 上传整个仓库或大批文件前，先确认 .gitignore、秘密扫描结果和历史提交中没有凭据。
• 了解所用 AI 工具对数据保留、训练使用的设置，并按项目要求配置。
• 对大段采纳的生成代码或外部片段，关注许可证兼容与来源；按项目策略决定是否记录”AI 辅助”标记。

12. 错误处理、日志与可观测性

12.1 错误分类

• Validation Error：输入不合法；
• Business Error：违反业务规则；
• System Error：内部系统故障；
• External Error：依赖服务或网络故障。

分类的意义在于决定行为：Validation/Business 直接返回给用户且不重试；External 可退避重试；System 需要告警。

12.2 要求

• 不吞异常、不使用空 catch、不只打印日志后假装成功。
• 错误要被正确返回、传播、转换、重试或降级，并记录必要上下文。
• 使用结构化日志，携带 request/trace/task ID 等关联标识。
• 指标关注延迟、吞吐、错误率、队列积压、资源消耗和关键业务指标。
• 后台任务明确状态、进度、取消、重试次数、失败原因和恢复策略。
• 日志不是数据库；关键业务状态应持久化到合适的数据存储中。

13. 测试策略与质量门禁

13.1 测试金字塔

• 单元测试：业务规则、边界、状态机、错误映射。
• 集成测试：数据库、文件系统、外部服务适配器、消息处理。
• 契约测试：API、事件、第三方集成。
• E2E 测试：关键用户路径，数量保持精简。
• 性能/压力测试：对吞吐、延迟、内存、并发与大数据量有明确目标时执行。

13.2 AI 生成测试的质量要求

AI 容易写出”照着实现抄一遍”的测试，这类测试永远通过，却不保护行为。因此：

• 测试断言行为与契约，而不是复述实现细节。
• Bug 修复先写出在修复前会失败的复现测试，并确认其确实失败。
• 禁止为了让测试通过而削弱、跳过或删除测试；修改既有测试必须说明原因。
• 核心逻辑可定期用变异测试（cargo-mutants、Stryker、PIT 等，视技术栈）检查测试是否真能发现缺陷。
• 慎用”全部 mock”；用集成测试验证真实边界。
• 每个测试至少一个对可观察结果的断言；只断言”没抛异常”不算测试。

13.3 覆盖率

核心业务代码可以将 80% 作为起始目标，但覆盖率不是质量证明。优先覆盖高风险逻辑、边界条件、异常路径、权限判断、并发与数据一致性。对低价值生成代码或简单 glue code，可用风险解释替代机械追求数字。

有效的自检问题不是”这行被覆盖了吗”，而是”如果这行写错了，哪个测试会红”。

13.4 每个功能至少检查

正常路径；空值、缺失字段、非法输入；最小/最大/边界值；权限不足；外部依赖超时、失败、重复响应；并发、重复请求、取消；持久化失败、部分成功、重启恢复；兼容性和回归；日志是否泄露敏感信息；非默认 locale 与超长文案（适用时）。

13.5 质量门禁

CI 至少执行：格式化检查；lint / 静态分析；类型检查（适用时）；单元测试；关键集成测试；构建；依赖/秘密扫描；文档一致性检查（适用时）。

任何门禁失败都不能被 AI 静默忽略。若暂时无法修复，必须记录原因、影响、责任人与后续计划。

14. 文档同步规则

14.1 影响分析

每次变更前做影响分析，每次变更后检查下列内容是否需要更新：

文档应解释”为什么、约束是什么、如何验证”，而不只是复制代码。对纯内部、无语义影响的小改动不必更新所有文档，但必须做过影响判断，并在提交信息或 PR 描述中留下结论。

14.2 自动检查

建议提供 docs-check，扫描：未更新的规格引用、过期命令、缺失迁移说明、失效链接、不一致的 API 示例、AGENTS.md 声明的命令是否真实存在。即使只实现前三项，也能挡住大部分漂移。

14.3 文档不应做的事

• 不要用文档弥补实现缺陷（“文档写了就行”）。
• 不要重复代码里已经清楚表达的内容，文档写约束和意图。
• 不要让同一事实存在两份。

15. Git 与变更管理

15.1 基本规则

• 开始前检查 git status、分支与最近提交。
• 禁止重置、清理、覆盖用户已有未提交变更。
• 每个提交聚焦一个逻辑目的；避免将格式化、重构和功能混在一起。
• 提交前审查 git diff 与 git diff --staged。
• 不提交密钥、构建产物、真实数据和临时文件。
• 大规模重构分阶段进行，保持每个阶段可编译、可测试。
• 自动 commit 默认关闭或需明确配置；push、发布和生产操作始终单独授权。
• 对 schema、公开 API、配置格式和持久化格式变更，记录兼容与回滚策略。

15.2 AI 协作下的额外约定

• 一个 AI 任务一个提交。任务边界已在阶段 3 定义清楚，把它映射到提交边界，出问题时整体 revert，不必在混合 diff 里挑拣。
• 提交信息说明为什么，并记录验证方式与未验证项；“AI 生成”不是理由也不是免责。
• 破坏性操作（历史重写、强制推送、删分支）永不自动执行，即使任务说明里”看起来”允许。
• 若项目要求可追溯，可在 commit trailer 记录辅助工具与模型版本（如 Assisted-by:）。

16. 代码审查清单

16.1 审查项

审查不能只看代码风格，至少检查：

• 需求和验收标准是否满足？是否超出任务范围？
• 架构依赖方向是否正确？是否有重复逻辑、过度抽象或不必要依赖？
• 输入校验、权限检查、错误处理是否完整？
• 并发、取消、超时、重试与幂等是否正确？
• 数据库约束、事务、索引和迁移是否合理？
• 日志、指标和敏感信息处理是否适当？
• 测试是否覆盖正常、边界和失败路径？测试是否真的保护行为，而非复述实现？
• 新增依赖是否经过人工核实（来源、许可证、必要性、锁文件 diff）？
• 文档是否与实际行为一致？
• 是否存在兼容性、性能、资源泄漏或可恢复性风险？
• 变更是否容易理解、回滚和继续维护？能否在不看代码的情况下听懂实现思路？
• 是否存在第 8 章列出的反模式？

逐项勾选版本见 A.6。

16.2 审查结果分级

审查者应优先报告 Blocker 与 Major，并给出具体位置 + 触发条件 + 影响 + 修复建议；只给”建议优化一下结构”这类结论，对作者没有可执行价值。

17. 技术栈配置

所有栈共用的一条：UI / 表现层不承载业务规则与持久化逻辑，分层与依赖方向见第 6 章。下面只列各栈特有的命令、扫描工具与平台约束；未列出的栈按同样结构自行扩展。

17.1 Rust / CLI / 服务端

• 命令：cargo fmt --check、cargo clippy --all-targets --all-features -- -D warnings、cargo test。
• 扫描：cargo audit 或 cargo deny check（许可证、来源、漏洞）。
• 明确错误类型与上下文；谨慎使用 unwrap() / expect()，只在确有不变量保证处使用。
• 评估 async 任务取消、锁竞争、共享状态、生命周期和资源释放。
• 对不可信输入、文件路径、网络请求与反序列化做边界校验。

17.2 Tauri / React / WebView 桌面应用

• 前后端命令定义稳定契约；对参数和返回值做校验。
• 权限、文件系统访问、shell 调用和 IPC 命令遵循最小权限；用 Tauri 的权限/capabilities 机制限定可用命令，并配置严格 CSP。
• 明确 UI 状态、异步状态、错误状态、空状态、加载状态和取消行为。
• 测试核心逻辑、IPC 边界、打包产物与目标平台行为。

17.3 Rust + GPUI 桌面应用

• 业务状态、命令、事件、调度器和持久化分离；GPUI 只作表现层。
• 明确 UI 线程与后台异步任务的消息传递和生命周期。
• 长任务提供取消、进度、失败原因和恢复机制。
• Windows 集成（通知、剪贴板、文件选择、系统代理）通过平台适配层隔离。
• 验证目标平台构建、窗口生命周期、资源释放和高负载 UI 响应。

17.4 TypeScript / Node（Web 前端与后端）

• 命令：tsc --noEmit（或框架 typecheck 脚本）、eslint .、prettier --check .、vitest run。
• 扫描：npm audit / pnpm audit；提交前检查锁文件 diff。
• tsconfig 开启 strict，边界处禁用 any；外部输入（请求、环境变量、存储读取）用 zod 等做运行时校验——类型只在编译期有效。
• 服务端状态与本地 UI 状态分开管理，避免把所有数据塞进全局 store。
• 异步边界显式处理取消（AbortController）、超时与错误状态，不把 promise 悬空。
• 前端能读到的环境变量即公开信息，密钥不得放在前端。

17.5 .NET / C#（含 WPF 桌面）

• 命令：dotnet format --verify-no-changes、dotnet build -warnaserror、dotnet test。
• 扫描：dotnet list package --vulnerable --include-transitive；启用 NuGetAudit。
• 开启可空引用类型（<Nullable>enable</Nullable>），把警告当错误；async 全链路，禁止 .Result / .Wait() 同步阻塞。
• 分层落位：App（UI/宿主）→ Platform（平台集成）→ Core（领域与持久化）；Core 不引用 UI 与平台库。
• WPF 特有：业务逻辑不进 code-behind，走 MVVM 与命令绑定；Dispatcher 与后台线程的切换点显式化；长任务支持 CancellationToken 与进度上报。
• EF Core：迁移版本化并提交，禁止生产用 EnsureCreated；连接串走配置；关注 AsNoTracking、Include 造成的 N+1 与笛卡尔爆炸。
• 测试：xUnit 测 Core 层纯逻辑；持久化用临时 SQLite/容器做集成测试，而不是全 mock DbContext。

17.6 Java / 后端服务

• 命令：mvn -q verify / ./gradlew check；接入 Checkstyle/Spotless 与静态分析。
• 事务边界由业务用例（Application Service）定义，Controller 不直接操作数据库。
• 并发更新使用乐观锁（版本列）、条件更新或数据库约束。
• 接入依赖漏洞扫描（如 OWASP Dependency-Check）；日志结构化并带 trace id，异常不丢 cause 链。

17.7 Python（服务端 / 脚本 / 数据管道）

• 命令：ruff check .、ruff format --check .、mypy .（或 pyright）、pytest。
• 扫描：pip-audit；依赖用锁文件（uv / poetry / pip-tools）固定。
• 边界处标注类型：外部输入、公共 API、数据结构；内部实现可省略，但不要用类型标注骗过检查。
• 虚拟环境隔离，禁止全局 pip install；脚本入口与库代码分开。
• 数据管道显式处理 schema 变化与空值语义，不依赖 NaN 传播。
• 捕获具体异常（except ValueError），避免裸 except: 与静默 pass。

17.8 Go（服务端 / CLI）

• 命令：gofmt -l .、go vet ./...、staticcheck ./...、go test -race ./...。
• 扫描：govulncheck ./...。
• 错误用 %w 包装保留链；不用字符串比较判断错误类型。
• 显式传递 context.Context，所有阻塞调用支持取消；goroutine 必须有退出路径。
• 接口在使用方定义且保持小；不为”以后可能用到”预留接口。

18. Definition of Done（完成定义）

一个功能只有同时满足适用项才算完成。

L0 变更可只检查标注 ★ 的项，且 ★ 项按 1.2 表中 L0 一列的口径执行（例如测试项为”现有测试通过；Bug 修复需回归测试”，不要求新写边界与失败路径测试）。

• ☐ 规格与验收标准已确认；
• ☐ 设计与任务范围明确；
• ☐ ★ 实现满足业务规则且无已知阻断问题；
• ☐ ★ 本次改动涉及的逻辑路径有测试；Bug 修复含修复前会失败的回归测试；
• ☐ ★ 格式化、lint、类型检查、测试和构建通过，或未通过项已记录原因与计划；
• ☐ ★ 能讲清本次变更的实现思路与关键取舍（理解债门槛）；
• ☐ 安全、权限、敏感信息和依赖风险已检查；新增依赖已人工核实；
• ☐ 日志、错误处理、超时、重试、取消和恢复策略适用且明确；
• ☐ 数据库/API/配置变更有迁移与兼容策略；
• ☐ 受影响的规格、架构、API/DB 文档、README、CHANGELOG 已同步，或已说明为何不同步；
• ☐ ★ Git diff 无无关修改、密钥、临时文件或意外生成产物；
• ☐ ★ 验证结果附有原始证据；已知限制、未验证事项和回滚方案已报告；
• ☐ ★ 提交、推送、发布等操作遵守授权边界。

19. 最小落地路线与度量

19.1 落地路线

不要一次建设过度复杂的系统。

第 0 步（2–4 周）：记录基线。 引入规范前先量现在的数，否则改进无法证明（口径见 19.2）。

第 1 周：规范先行。 建 AGENTS.md、CLAUDE.md、.ai/constitution.md；放入风险分级与附录 A 的模板；选一个真实项目试跑。

第 2 周：质量门禁。 统一并固化格式化/lint/类型检查/测试/构建命令；接通 CI；把能自动化的检查变成机器门禁。

第 3 周：可复用能力。 盘点已有模块与模板，给成熟模块补齐 README、示例、测试与兼容策略；建立项目类型配置。

第 4 周：自动化与迭代。 实现 inspect、docs-check、release-check（见附录 D）；对照基线复盘。

19.2 度量口径

指标要有定义和取数方式，否则只会变成感觉。

20. 最终执行原则

AI 负责加速分析、设计、实现和审查；工程流程负责约束风险；自动化工具负责验证；人类负责目标、取舍和高风险授权。

衡量成功的指标不是”AI 写了多少代码”，而是：

• 需求返工是否减少；
• 关键缺陷是否更早发现；
• 变更是否更容易理解和回滚；
• 测试与文档是否可靠；
• 新项目是否能快速继承成熟能力；
• 项目是否能在更换模型或开发者后继续维护。

任何规则若无法自动验证，至少应进入审查清单；任何高风险操作若无法安全自动化，应保留明确的人类审批步骤。

最后一条：不要让工程规则只活在提示词里。能写进配置、钩子、CI 和模板的约束，才是真正生效的约束；其余都只是建议。

附录 A：最小模板

模板是”填什么”的唯一出处；正文只写”为什么”和”什么时候容易出错”。空白章节不必强行填满，但留下空白的章节，说明那件事还没想清。

A.1 spec.md

# <功能名> 规格
状态：Draft | Accepted | Implemented | Superseded　风险等级：L0 | L1 | L2　日期：
关联：<issue / ADR / 上游需求>

## 背景与问题
## 目标 / 非目标
## 用户场景与业务规则
## 功能需求 / 非功能需求
## 数据与接口（输入、输出、状态变化、权限）
## 验收标准
- Given <前置> When <动作> Then <可观察结果>
## 异常与边界场景
## 依赖、风险、迁移与回滚
## 已确认事实 / 假设 / 待确认问题

A.2 plan.md

# <功能名> 实施计划
## 现状与可复用资产
## 方案概述（模块职责、依赖方向、数据流）
## 数据模型与接口契约
## 错误处理、安全与可观测性
## 测试策略
## 备选方案与取舍
## 风险与回滚方案

A.3 tasks.md

# <功能名> 任务清单
总览：<任务数>｜顺序：TASK-001 → 002 → …

## TASK-001 <标题>
- 目标与范围：
- 依赖：
- 允许修改的范围：
- 实现步骤：
- 验收标准：
- 验证命令：
- 风险等级 / 回滚方式：
- 文档更新项：
- 状态：Todo | Doing | Done

## TASK-002 <标题>
（同上）

A.4 verification.md

# <功能名> 验证记录

**环境**：<OS / 运行时与版本 / 关键工具版本>
**提交**：<commit hash>　**日期**：

| 命令/检查 | 结果 | 原始证据（关键输出片段 / 链接） |
|---|---|---|
| <cmd> | 通过 / 失败 / 未执行 | |

## 未验证事项及原因
## 已知限制
## 剩余风险
## 回滚方案

A.5 ADR

# ADR-<编号>：<决策标题>
状态：Proposed | Accepted | Superseded by ADR-<n>　日期：
关联：<spec / task / issue>

## 背景
## 决策
## 备选方案及放弃原因
## 影响与后果（正面 / 负面 / 需要后续跟进）

A.6 review-checklist.md

# 审查清单：<PR / 变更标题>
审查者：　日期：　变更等级：L0 | L1 | L2

## 范围与需求
- ☐ 满足验收标准，未超出任务范围
- ☐ 规格与实现一致；不一致处已明确修哪一方
- ☐ 能听懂实现思路（理解债检查）

## 正确性
- ☐ 输入校验、权限检查完整
- ☐ 错误处理不放任、不吞异常
- ☐ 并发 / 取消 / 超时 / 重试 / 幂等正确
- ☐ 数据库约束、事务、索引合理
- ☐ 迁移有回滚与兼容窗口考虑

## 测试
- ☐ 覆盖正常、边界、失败路径
- ☐ 断言针对行为，而非复述实现
- ☐ Bug 修复有修复前会失败的回归测试
- ☐ 未削弱或删除既有断言（若有，已说明理由）

## 安全与依赖
- ☐ 无密钥、令牌、敏感数据进入代码/日志/测试快照
- ☐ 新增依赖已人工核实（来源、许可证、必要性、锁文件 diff）
- ☐ 未为通过检查而降低安全配置

## 文档与可维护性
- ☐ 受影响文档已更新或已说明为何不更新
- ☐ diff 无无关格式化、重构或生成产物
- ☐ 存在第 8 章反模式？（逐项排查）
- ☐ 变更可回滚

## 结论
Blocker：　Major：　Minor：　Nit：
最终判定：通过 / 需修改 / 拒绝

A.7 progress.md

用于长任务的进度与交接（见 7.2）。

# <功能名> 进度记录
更新：<日期时间>

## 当前目标
## 已完成（含提交 hash）
## 已验证（命令 + 结果摘要）
## 未验证 / 待办
## 关键决策与理由
## 已知风险与阻塞
## 下一步（可直接执行的动作）
## 上下文交接说明（新会话需要知道的最小信息）

A.8 AGENTS.md（入口文件）

只放这四块。流程细节不放这里，见 5.2。

# 项目协作规则

## 项目概述
<一两句话：做什么、技术栈、目标平台>

## 常用命令
- 格式化：<cmd>
- Lint：<cmd>
- 测试：<cmd>
- 构建：<cmd>

## 工作方式
- 开始前：读相关规格/架构/测试；检查 `git status`；不得覆盖用户未提交变更。
- 先分析再动手；一次只做一个有边界的任务；最小 diff，不做范围外重构。
- 不虚构 API、库能力或测试结果；不声称运行过未执行的命令。
- 完成前运行上述命令，并用原始输出报告结果、未验证项和回滚方案。

## 硬性禁令（需人类明确授权）
- push / 发布 / 生产迁移 / 删除数据 / 破坏性 git 操作 / 新增依赖 / 修改公开 API 与数据库结构 / 触碰密钥。

## 详细规范
- 工程宪章：.ai/constitution.md
- 架构：docs/architecture/
- 工作流：.ai/workflows/

附录 B：常用工作流提示词

放在 .ai/workflows/，按需引用。每条都假定入口文件已生效。

B.1 项目发现

先不要修改任何文件。请检查仓库结构、Git 状态、入口、技术栈、测试和 CI、代理规则、规格与架构文档。
识别现有约束、可复用模块、重复实现、风险和缺失信息。
输出 Project Discovery 报告，并提出下一步计划。不得覆盖用户未提交的变更。

B.2 功能规格

请为 <功能> 编写规格，不要开始编码。字段见 .ai/templates/spec.md。
包含：背景、目标、非目标、用户场景、业务规则、功能/非功能需求、数据与接口、状态变化、
正常/边界/失败场景、权限、安全、兼容性、验收标准、风险、未决问题，并建议风险等级（L0/L1/L2）。
把已确认事实、假设和待确认问题分开；关键业务假设先提问。

完成后单独回答一句：这个方案的前提是否成立？是否存在更简单的实现路径？

B.3 架构与任务计划

基于已确认规格，先分析现有架构和可复用能力。
给出模块职责、依赖方向、数据流、接口契约、数据模型、错误处理、测试策略、风险和回滚方案。
记录重要决策为 ADR。随后拆分可独立验证的任务，每项写明依赖、范围、验收标准和验证命令。
先等待审查，不要直接批量实现。

B.4 单任务实现

只实现任务 <TASK-ID>。先阅读规格、架构、相关代码和测试，并检查 Git 状态。
先列出计划和影响范围，再做最小必要修改。补齐正常、边界和失败路径测试；
Bug 修复须先给出修复前会失败的复现测试。不得削弱或删除既有测试，不得擅自新增依赖。
完成后执行实际可运行的验证命令，检查 diff、文档、依赖和安全风险。
报告实际结果时附上原始输出片段；不得声称运行过未执行的命令。

B.5 反模式自查

对照 AI 协作反模式清单（第 8 章）检查刚才的改动，逐条给出"存在 / 不存在 / 不适用"及依据：
大爆炸式生成、代码缝合怪、假装完成、生造 API、注释膨胀、顺着错误前提、过度抽象、
自证循环、重试到绿、mock 泛滥、断言缺位、声称跑过、覆盖率刷分。
只报告真实存在的问题，不要为了显得认真而罗列不存在的项。

B.6 独立审查（使用新会话或不同模型）

请作为独立审查者检查本次变更，而不是替实现辩护。输入仅包含规格、diff 与测试结果。
对照规格和验收标准，检查正确性、安全、数据一致性、并发、性能、架构、测试质量、文档、兼容性与回滚。
另外检查是否存在 AI 协作反模式（代码缝合怪、自证循环、断言被削弱、stub 冒充实现）。
按 Blocker / Major / Minor / Nit 分级，给出具体文件/位置、触发条件、影响和修复建议。
先报告会阻断交付的问题，不要只给泛泛建议。

B.7 文档一致性

根据当前 Git diff 和已验证行为，做文档影响分析（影响面见第 14 章的表格）。
只更新真正受影响的文档；不要凭猜测写入未验证行为。
列出已更新和无需更新的文档及理由。

B.8 提交前检查

执行提交前检查：Git 状态、diff、格式化、lint、类型检查、测试、构建、秘密扫描、迁移风险、文档一致性。
列出每条命令及真实结果（附关键输出片段）、未执行项及原因、剩余风险、回滚方案和建议提交信息。
不要 push、发布、执行生产迁移或其他不可逆操作，除非获得明确授权。

附录 C：案例：桌面应用（下载器类）的实践

以”Rust + GPUI + Tokio 的下载管理器”为例。这类应用的价值在于下载调度、HTTP 引擎、持久化和恢复，而不只是 UI；正确性、文件完整性、任务恢复和数据安全优先于功能数量与视觉效果。

C.1 推荐开发顺序

1. Workspace 与构建基线；
2. 核心领域模型、状态机、命令/事件；
3. 持久化与迁移；
4. HTTP 下载引擎与文件安全；
5. 调度、并发、限速、重试；
6. 暂停/取消/崩溃恢复；
7. GPUI UI；
8. Windows 平台集成；
9. 性能优化；
10. 再增加 HLS、DASH、yt-dlp、Torrent、浏览器集成等后端。

不要在 HTTP MVP 稳定前同时开发所有下载后端。

C.2 关键验证

• 本地 HTTP 测试服务器；
• Range 支持与不支持、服务器中断、超时、限速；
• 部分文件、磁盘写入失败、磁盘空间不足；
• 暂停、取消、重试、进程崩溃与重启恢复；
• 大文件、并发任务、内存占用与句柄释放；
• cargo fmt、cargo clippy、cargo test、Windows 构建；
• 任务状态、文件临时态和最终文件之间的一致性。

C.3 这类项目的典型反模式

• 先做 UI 再补状态机 → 状态逻辑散落在视图回调里，恢复逻辑无处安放；
• 直接写最终文件，失败后留半截 → 用临时文件 + 原子重命名 + 校验；
• 一个”全局下载管理器”单例持有所有锁 → 取消与并发死锁高发；
• 靠 sleep 轮询进度 → 内存与 CPU 双高，取消延迟大。

附录 D：自动化与可复用能力库（设想）

本节是目标形态，不是现成工具。可先用脚本与文档落地，再逐步工具化。

D.1 项目初始化器

目标是让新项目自动获得一致的工程底座，而不是每次靠长提示词重新解释。应能做到：

• 识别项目类型、语言、框架、平台、数据库、测试工具；
• 扫描现有仓库，禁止盲目覆盖；
• 生成宪章、代理指令、目录结构、模板与 CI 配置；
• 运行可执行的验证并记录结果，是否自动 commit 由配置决定。

设计约束：覆盖行为可预测；模板升级不静默覆盖项目自定义内容；配置字段校验并版本化。

project:
  name: example-app
  type: desktop          # web | backend | desktop | cli
  language: rust
  target_platforms: [windows]
quality:
  coverage_target: 80
  require_docs_sync: true
  require_explanation_before_commit: true   # 理解债门槛（第 18 章）
agent:
  network: restricted    # restricted | allowlist | open
  require_approval_for: [push, migrate, delete, publish, install]
git:
  one_commit_per_task: true

D.2 复用决策

盘点 → 确认语义匹配（不是名字相似）→ 复用或重写。

每个可复用资产至少要有：适用/不适用场景、测试、版本兼容、维护人。优先”稳定接口 + 小而清晰的实现”，避免过早建设大而全的框架。

附录 E：术语表

只收录正文未展开解释、且容易混淆的词。

AI 辅助软件工程最佳实践手册