AI辅助开发中的文档即代码：八层文档体系与对抗性审查实践

1. 项目概述：一个为AI辅助开发而生的“文档即代码”工程模板

如果你和我一样，在过去一年里深度使用Cursor、Claude Code这类AI编程工具，那你一定经历过这种“信任崩塌”的时刻：项目初期，AI生成的文档看起来条理清晰、逻辑完备，你满怀信心地推进。但到了项目中期，当你需要修改一个半年前的功能，或者新成员加入团队时，问题就暴露了——文档里的API路径已经失效，示例代码无法运行，架构图与实际代码严重脱节。更糟糕的是，你根本不知道哪些部分可信，哪些是AI的“幻觉产物”。这种“文档债”就像技术债的孪生兄弟，悄无声息地积累，最终在项目最需要稳定性和可维护性的时候爆发。

这正是我花了大半年时间，结合十多个实际项目的教训，打磨出这个aivalueworx/template-ai-project模板的核心原因。它不是一个简单的文档生成器，而是一套完整的“复合工程”体系。简单说，它把文档当作代码一样来管理：版本控制、分层设计、自动化测试、持续集成。这个模板预置了从代码注释到架构决策记录（ADR），从AI上下文管理到对抗性代码审查的八层文档结构，并且通过GitHub Actions和Cursor Automations实现了全自动化的文档同步与质量检查。

无论你是独立开发者，还是带领一个小型技术团队，只要你正在或计划使用AI辅助工具进行软件开发，这个模板都能帮你建立起一套可扩展、可信赖的文档工作流。它解决的不仅仅是“写文档”的问题，更是如何让AI成为你团队中一个可靠、可控、可审计的“数字同事”，而不是一个会制造混乱的“黑盒助手”。

2. 核心理念与架构设计：为什么是“八层文档”？

2.1 从“文档幻觉”到“文档即代码”的范式转变

传统软件开发中，文档往往是事后的、手动的、容易过时的附属品。而在AI辅助开发中，这个问题被急剧放大。AI工具（如Cursor的“Edit with Instructions”或Claude Code的会话）能够以惊人的速度生成大量文本，但这些文本缺乏真实的项目上下文和历史决策记忆。它们可能基于过时的代码快照、错误理解的需求，甚至凭空捏造出看似合理但完全错误的实现细节。我把这种现象称为“文档幻觉”——文档与代码现实严重脱节，却披着权威的外衣。

这个模板的基石，是“文档即代码”的工程理念。这意味着：

1. 版本控制一切：所有文档（包括AI的上下文记忆、会话摘要）都纳入Git管理，每一次变更都有迹可循。
2. 自动化生成与同步：利用工具链（如files-to-prompt、llm）从代码和测试中提取信息生成文档草稿，并通过CI/CD（如GitHub Actions）确保关键文档（如README、CHANGELOG）随代码更新而自动更新。
3. 结构化与分层：不同类型的文档有明确的位置、格式和责任人，避免信息混杂。
4. 人类最终审核：对于核心决策（架构、事后复盘、AI代理约束），设置保护分支（CODEOWNERS），禁止AI直接修改，确保人类智慧的最终把控。

2.2 八层文档体系详解：每层的职责与交互

模板的核心是八个清晰分层的文档结构，这借鉴了“复合工程”的思想，即让每一层文档服务于特定的受众和目的，并且下层为上层提供上下文，上层为下层提供约束。

第一层：代码级文档（AI辅助，人工校验）这是最基础的一层，包括代码中的行内注释和函数/类的文档字符串（如JSDoc、TSDoc、Python docstrings）。AI可以很好地生成这些内容，但必须人工校验其准确性。模板通过.cursor/rules/docs-docstrings.mdc等规则文件，强制要求对导出的函数添加文档字符串，但内容本身需要开发者复核。

注意：不要依赖AI生成复杂的算法解释或业务逻辑注释。AI擅长描述“是什么”，但容易在“为什么”这个关键点上出错。这一层的原则是：AI生成草稿，人类校验意图。

第二层：系统级文档（AI搭建脚手架，人类填充与评审）包括项目总览README.md、API接口规范docs/templates/openapi.yaml和新成员入职指南docs/templates/ONBOARDING.md。AI可以根据代码结构生成README的框架和OpenAPI的基本路径，但项目愿景、核心价值、复杂的业务流程图、API的详细业务约束等，必须由人类完成。实操要点：利用uvx files-to-prompt工具将src/目录下的代码喂给Claude，提示它“基于此代码库生成一个README.md的架构概述部分”，可以快速获得一个高质量的初稿，大幅提升效率。

第三层：运维文档（AI创建模板，人类填充具体步骤）包含运维手册docs/runbooks/和故障复盘报告docs/postmortems/。AI可以根据系统监控指标或错误日志，建议一个故障排查的步骤模板，但具体的命令、权限、内部系统链接、涉及的具体团队联系人，必须由运维工程师或开发者填写。postmortems目录被CODEOWNERS严格保护，禁止AI写入，确保复盘文化的纯粹性和无责性。

第四层：过程与决策文档（人类专属领域）这是项目的“大脑”所在，包括架构决策记录docs/adr/和决策日志DECISIONS.md。ADR记录重要的、不可逆的技术选择及其上下文（背景、选项、决策、后果）。AI可以创建一个符合模板的ADR文件占位符，但“决策”和“理由”部分必须留空，由人类团队讨论后填写。DECISIONS.md则是一个轻量级的决策索引和日志。

第五层：AI上下文与记忆（版本控制，由AI维护）这是让AI在多次会话中保持“记忆”和“一致性”的关键。它包含一系列给AI看的“项目圣经”：

• AGENTS.md:核心上下文文件。定义了项目是什么、目标用户、核心技术栈、当前状态、下一步优先级。所有AI会话都应从此文件开始。
• CONVENTIONS.md: 编码规范、命名约定、测试标准。
• DECISIONS.md: 指向第四层决策的索引。
• HANDOFF.md: 跨会话任务状态记录。每次会话结束前，AI应更新此文件，说明“我做了什么”、“遇到了什么坑”、“接下来建议谁（或哪个AI）做什么”。
• MEMORY.md: Claude Code专用，索引其.claude/memory/目录下的记忆文件。
• TRANSCRIPT_LOG.md: 重要AI会话转录稿的索引，链接到GitHub Gist。

第六层：智能体工作流（AI生成，人类评审）这是一套标准化的AI协作流程模板，位于docs/agentic-workflow/：

1. PRD-TEMPLATE.md(产品需求文档): 在开始任何重要功能前，先让AI或产品经理填写此模板，明确目标、范围、成功指标。
2. PLAN-TEMPLATE.md: PRD评审通过后，AI或架构师据此制定技术实施方案。
3. TASKS-TEMPLATE.md: 执行阶段，将计划拆解为具体的、可勾选的任务项。
4. SCRATCHPAD-TEMPLATE.md: 临时会话工作区，用于记录思路、尝试和错误，此文件应被.gitignore或在提交时压缩。

第七层：智能体治理（人类指定，永不自动生成）随着AI代理（Agent）能力越来越强，必须为其设定行为边界。这层定义了“游戏规则”：

• AGENT_CONTRACT-TEMPLATE.md: 每个自主运行AI代理的“劳动合同”，明确其资源限制（如最多创建5个文件）、终止条件（如连续3次编译失败）、职责范围。
• TASK_CONTRACT-TEMPLATE.md: 基于MCP（Model Context Protocol）的跨代理任务委托协议。
• TOOL_REGISTRY.md: 所有可供AI调用的工具（如数据库查询、发送邮件API）的注册表及其模式定义。

第八层：可观测性与审查确保整个AI协作过程透明、可审计、可改进：

• OBSERVABILITY.md: 定义每次AI调用应该记录什么日志（输入、输出、所用工具、耗时）。
• CHALLENGE_PROMPTS.md:对抗性提示词库。这是模板的“安全网”，包含了在需求分析、设计、编码、测试等六个关键阶段，用于挑战AI方案的提示词，例如“请以安全专家的身份，找出这个API设计中的三个潜在漏洞”。
• REVIEW_GATE.md: 将上述挑战提示词映射到具体的CI/CD或自动化触发节点。

3. 快速上手指南与核心配置

3.1 五分钟初始化你的项目

假设你的项目叫my-awesome-ai-project，以下是具体步骤：

1. 使用模板创建仓库： 访问GitHub上的aivalueworx/template-ai-project仓库，点击绿色的 “Use this template” 按钮，然后选择 “Create a new repository”。输入你的仓库名my-awesome-ai-project并创建。

2. 克隆并打开项目：

   git clone https://github.com/你的用户名/my-awesome-ai-project.git cd my-awesome-ai-project # 使用 Cursor 或 VS Code 打开 cursor . # 或者 code .

3. 填充人类专属内容（最关键的一步）： 在项目根目录下，执行一个简单的搜索替换脚本（模板提供了setup.sh的雏形，你需要完善它），或手动全局搜索以下占位符并替换：

   • REPLACE-WITH-DATE: 替换为当前日期，如2025-10-27。
   • [org]/your-org/engineering: 替换为你的GitHub组织或个人用户名。
   • [YOUR-REPO],[YOUR-ORG]: 替换为你的仓库名和组织名。
   • 重点：找到AGENTS.md和CONVENTIONS.md文件中被<!-- HUMAN-AUTHORED -->注释包裹的区块。这是你必须亲自填写的项目核心上下文。例如，在AGENTS.md中，你需要清晰定义：
     • 项目一句话介绍：我们正在构建什么？为谁解决什么问题？
     • 技术栈：主语言、框架、数据库、核心依赖库及其版本。
     • 当前状态：项目处于什么阶段？下一个里程碑是什么？
     • 禁忌与偏好：我们绝对不用的技术是什么？代码风格有何特殊要求？

4. 配置Cursor规则与自动化： 模板在.cursor/rules/目录下预置了多个规则文件（.mdc后缀）。这些规则定义了当你在特定文件上工作时，Cursor AI应该遵循的额外指令。你需要根据你的项目调整它们。例如，docs-api.mdc规则可能包含“当修改src/api/下的文件时，请同步更新docs/templates/openapi.yaml文件中的对应路径描述”。详细配置指南见docs/cursor-automations-setup.md。

3.2 核心工具链安装与配置

为了充分发挥模板的威力，建议安装以下工具链，它们主要来自Simon Willison的实践，用于捕获和管理AI会话历史。

# 1. 安装 llm 命令行工具，用于记录和查询所有LLM交互 pip install llm # 设置你的默认模型（例如使用OpenAI API） llm keys set openai # 现在，任何通过`llm`命令进行的对话都会被自动记录到SQLite数据库 llm "帮我写一个Python函数，计算斐波那契数列" # 查看日志数据库位置 llm logs path # 使用Datasette以网页形式浏览所有对话历史（非常强大！） uvx install datasette datasette "$(llm logs path)"

# 2. 安装 Claude Code 会话导出工具 uvx install claude-code-transcripts # 将最近一次Claude Code会话导出为HTML并发布为GitHub Gist（需要提前配置gh CLI认证） uvx claude-code-transcripts --gist # 或者导出所有历史会话到本地docs/transcripts/目录进行归档 uvx claude-code-transcripts all -o docs/transcripts/

# 3. 安装 files-to-prompt，用于从代码生成文档草稿 uvx install files-to-prompt # 示例：生成src目录下所有TypeScript文件的架构概述 uvx files-to-prompt src/ -e ts -c | llm -m gpt-4 -s '请基于这些代码，撰写一份简洁的架构概述，用于README.md' # 示例：基于测试文件生成使用示例文档 uvx files-to-prompt tests/ -e py -c | llm -m claude-3.5-sonnet -s '请提取这些测试中的用例，编写用户使用指南'

配置要点：将这些工具的常用命令封装成项目package.json中的scripts，或写在docs/OBSERVABILITY.md里，方便团队新成员一键安装和统一使用。

3.3 理解并配置“复合工程”循环

模板设计了一个闭环的工作流，我称之为“复合工程循环”。理解它，你就理解了整个模板是如何运作的：

1. 会话开始：当你启动Cursor或Claude Code时，一个预置的钩子（hook）会自动将MEMORY.md（上次会话的偏好记忆）和HANDOFF.md（待办任务）注入到AI的上下文。
2. 上下文加载：AI首先阅读AGENTS.md,CONVENTIONS.md,DECISIONS.md，获得项目全景和规则。
3. 结构化执行：AI遵循PRD -> PLAN -> TASKS的模板来开展工作，确保工作有规划、可追踪。
4. 对抗性审查：在关键节点（如设计完成、代码写完），你或自动化工具可以触发@challenge命令，使用CHALLENGE_PROMPTS.md中对应阶段的提示词对AI的工作成果进行“挑刺”。
5. 文档同步：工作完成后，通过/doc-sync技能（Cursor）或类似自动化，将更新的文档（如更新的README、新的ADR占位符）提交并推送。
6. 知识沉淀：会话结束时，AI更新HANDOFF.md，记录进度和后续建议。如果是一次重要的设计会话，使用claude-code-transcripts --gist导出对话，并将Gist链接记录到TRANSCRIPT_LOG.md。
7. 循环增强：本次会话中获得的经验教训（例如“发现使用X库时需要注意Y问题”）被人工或半自动地反馈到CONVENTIONS.md或AGENTS.md中。下一次会话开始时，AI就已经变得更“懂”这个项目了。

4. 深度配置：Cursor规则、GitHub Actions与对抗性审查

4.1 Cursor规则详解与自定义

Cursor的规则文件（.mdc）是控制AI在特定上下文中行为的强大工具。模板预置的规则位于.cursor/rules/目录下：

• docs-readme.mdc: 当AI编辑src/**或package.json时，此规则被激活。它会提醒AI：“如果你修改了核心功能或依赖，请检查README.md中的‘快速开始’或‘功能列表’部分是否需要更新。”这并非强制修改，而是一个智能提醒。
• docs-docstrings.mdc: 当AI在编写或修改一个即将被导出的函数/类时，此规则强制弹出提示：“请为这个公共API添加TSDoc/JSDoc注释。”这能有效保证代码自文档化的基础质量。
• docs-api.mdc: 关联到src/api/或类似路由目录。当AI新增或删除一个API端点时，规则会要求它“请同步更新docs/templates/openapi.yaml文件中的paths部分”。你可以在这里定义更细致的映射，比如根据HTTP方法生成不同的描述模板。
• docs-adr.mdc: 这是谨慎使用的规则。当AI进行了一项看似重大的架构变更（例如引入一个新的数据库客户端），此规则会触发，让AI在docs/adr/目录下创建一个新的ADR文件占位符，包含标题、状态、参与者等元数据，但必须将Decision和Rationale部分留空，并标记为<!-- HUMAN-AUTHORED -->，等待人类填写。
• committer.mdc: 定义了@committer命令的行为。当你在Cursor中键入@committer，AI会基于当前的代码变更和CONVENTIONS.md中的提交规范，生成一条符合Conventional Commits格式的提交信息，并执行git commit & push。
• challenge.mdc: 定义了@challenge命令。这是对抗性审查的入口。键入@challenge后，AI会根据当前项目阶段（通过分析最近修改的文件类型来推断），从CHALLENGE_PROMPTS.md中选取对应的提示词，对自己的工作成果进行批判性审视，并输出审查报告。

自定义规则建议：为你项目中特有的、容易出错的模式创建规则。例如，如果你的项目禁止使用eval()，可以创建一个security.mdc规则，当AI在代码中写入eval时，立即警告并建议替代方案。

4.2 GitHub Actions自动化流水线

模板在.github/workflows/下预置了三个核心工作流，开箱即用：

1. api-docs.yml:

   • 触发条件：推送至main分支，且修改了docs/templates/openapi.yaml或src/api/下的文件。
   • 执行动作：使用redocly或swagger-cli验证OpenAPI文件的语法正确性。如果验证通过，自动构建API文档网站（例如使用Redoc）并部署到GitHub Pages。
   • 价值：确保API文档永远与代码同步，且可供外部开发者随时查阅。

2. doc-staleness.yml:

   • 触发条件：定时任务（例如每周一早上9点），或手动触发。
   • 执行动作：运行scripts/check_doc_freshness.py脚本。该脚本会扫描关键文档（如README.md,docs/runbooks/*.md），检查其最后修改时间。如果某个文档超过设定的阈值（默认为90天），且其关联的源代码文件在此期间被修改过，则该工作流会失败，或在关联的PR上添加评论/自动创建Issue。
   • 价值：主动防御“文档过时”问题，将“更新文档”从靠人记得的职责，转变为CI系统强制执行的检查项。

3. readme-sync.yml:

   • 触发条件：PR合并到main分支后。
   • 执行动作：检查本次合并是否修改了package.json中的version字段。如果是，则自动更新CHANGELOG.md，在顶部添加一个新版本条目，并概括本次PR的提交信息。同时，它也会确保README.md中的版本号引用与package.json保持一致。
   • 价值：解放开发者，让版本管理和发布说明的更新变得自动化、无感。

4.3 对抗性提示词库的构建与使用

CHALLENGE_PROMPTS.md是模板的“灵魂”之一。它不是一个简单的列表，而是一个按软件开发阶段组织的、针对性的“提问清单”。其目的是让AI自己挑战自己，暴露设计缺陷。

如何构建有效的对抗性提示词？

• 阶段1（需求分析）：提示词应关注完整性和模糊性。例如：“假设你是一个极其挑剔的产品经理，请列出这个PRD中所有可能产生歧义的需求点，并为每个点提供一个反面案例。”
• 阶段2（架构设计）：提示词应关注可扩展性、复杂度和技术风险。例如：“你是一个有10年经验的SRE（站点可靠性工程师），请评估这个架构图。指出三个最可能成为单点故障的组件，并给出高可用性改进方案。”
• 阶段3（编码实现）：提示词应关注安全、性能和可维护性。例如：“你是一个专注于安全的代码审查机器人。扫描这段代码，找出所有可能的安全漏洞（如SQL注入、XSS、信息泄露），并按严重等级排序。”
• 阶段4（测试与评审）：提示词应关注覆盖率和边缘情况。例如：“你是一个专找边界条件的测试专家。针对这个函数，请给出5个会导致它失败或行为异常的极端输入参数组合。”

如何集成到工作流？REVIEW_GATE.md文件定义了这些提示词何时被触发。例如：

• PR打开时：自动运行阶段3（编码实现）和阶段4A（单元测试覆盖）的挑战提示，并将结果以评论形式贴在PR中。
• 在Cursor中手动输入@challenge：AI会分析当前工作区状态，推荐最适合的挑战阶段并执行。
• 每日构建后：对主干代码运行阶段2（架构设计）的轻量级挑战，监控架构漂移。

实操心得：对抗性审查最初可能会产生大量“噪音”（一些过于严苛或无关紧要的批评）。关键在于迭代和优化你的提示词。将AI提出的有效问题反馈到CONVENTIONS.md中，形成团队的“集体智慧”。例如，如果AI多次指出某类API缺少速率限制，就把“为公开API添加速率限制”写进规范。

5. 常见问题、排查与进阶技巧

5.1 初始化与配置问题

Q1: 克隆模板后，感觉文件太多太复杂，无从下手。A1: 这是正常反应。建议采用“分步启用”策略：

1. 第一周：只关注第1、2、5层。即：配置好AGENTS.md和CONVENTIONS.md，让AI在编码时能遵循基本规范并了解项目上下文。同时启用docs-docstrings.mdc规则，保证代码注释质量。
2. 第二周：引入第4层。在下次进行技术选型或重构时，手动创建一个ADR文件（复制模板），体验一下记录决策的过程。
3. 第三周：尝试第6层的工作流。在一个小功能开发中，严格走一遍PRD -> PLAN -> TASKS的流程。
4. 一个月后：当团队熟悉了基本流程，再逐步配置GitHub Actions和对抗性审查（第8层）。

Q2: Cursor Automations 在我的组织仓库里不触发，怎么办？A2: 这是Cursor目前（截至2026年初）的一个已知限制。解决方案有：

• 方案A（推荐）：将自动化配置转移到GitHub Actions中。模板里的很多自动化（如文档同步、过期检查）本身就有GitHub Actions版本。对于需要在编码过程中触发的（如@challenge），可以将其定义为Cursor的“自定义命令”，然后手动执行。
• 方案B：如果自动化对个人仓库有效，可以考虑将核心开发流程放在一个个人Fork的仓库中进行，通过频繁向组织主仓库提交PR的方式来协作。这虽然增加了PR数量，但能利用完整的自动化能力。
• 方案C：密切关注Cursor官方的更新。这个问题很可能在未来版本中得到解决。

Q3:TRANSCRIPT_LOG.md和导出Gist感觉很麻烦，有必要吗？A3: 对于个人项目或探索性编程，可能不是最高优先级。但对于团队协作和长期维护的项目，极其必要。它的价值在于：

• 知识传承：新成员可以通过阅读过去的决策对话，快速理解“为什么代码要这么写”，而不是只看“代码是什么”。
• 问题溯源：当出现一个奇怪的实现时，你可以通过Gist链接追溯到当时的对话，看是否是出于对某个库的误解或临时妥协。
• 审计轨迹：在合规要求高的行业，AI的决策过程需要被记录和审计。这些转录稿就是原始记录。简化技巧：不必记录每一次会话。只在完成一个功能模块、解决一个复杂Bug或做出一个重要架构决定后，有选择地导出并记录关键会话。

5.2 AI协作与工作流问题

Q4: AI总是忘记更新HANDOFF.md，或者写得很敷衍。A4: 这是一个提示工程问题。你需要强化在AGENTS.md或CONVENTIONS.md中对HANDOFF.md的更新要求。给出明确的模板和示例：

## 会话结束前必须更新 HANDOFF.md 格式如下： ### [日期] 会话总结 **完成的工作**： - 具体任务1（附上相关文件链接） - 具体任务2 **遇到的障碍/未解决问题**： - 问题描述（以及尝试过的解决方案） **下一步建议**： - 建议由 [@某人或某个AI技能] 在下次会话中处理 [具体任务] - 需要人类决策的事项：[列出事项]

同时，你可以在每次会话结束时，主动提醒AI：“请根据我们刚才的对话，更新HANDOFF.md文件。”

Q5: 对抗性审查（@challenge）产生的反馈质量不高，怎么办？A5: 提示词的质量决定了输出的质量。避免使用泛泛的“检查这段代码有什么问题”。要具体、要扮演角色、要限定范围。

• 差的提示：“审查一下这个函数。”
• 好的提示：“你是一个数据库性能专家。请审查下面这个SQL查询构建函数。重点关注：1. N+1查询风险；2. 索引使用是否合理；3. 是否存在全表扫描的可能。针对每个问题，给出具体的代码修改建议。” 此外，将高质量的审查结果作为示例，补充到CHALLENGE_PROMPTS.md对应的阶段后面，相当于给AI提供了“优秀审查”的样本。

Q6: 如何管理多个AI模型（如Claude、GPT）的上下文？A6: 模板的AGENTS.md、CONVENTIONS.md、DECISIONS.md是模型无关的，所有AI都应阅读。但对于模型特定的记忆：

• Claude Code：使用其内置的.claude/memory/系统和MEMORY.md索引。
• Cursor：利用项目级的.cursor/rules/和自定义指令来维护上下文。
• 通用技巧：在AGENTS.md的开头，可以添加一个“上下文摘要”章节，用最精炼的语言（例如500字以内）概括项目的核心信息。要求所有AI在开始工作前先阅读并复述这个摘要，确保它们抓住了重点。

5.3 维护与扩展

Q7: 随着项目发展，文档层越来越多，如何保持不混乱？A7: 定期进行“文档健康度检查”。可以将其设置为一个季度一次的团队活动，或者由Tech Lead负责。检查清单包括：

• 冗余检查：是否有不同文档重复描述了同一件事？是否可以合并？
• 过期检查：利用doc-staleness.yml工作流自动化的结果，集中处理过时文档。
• 效用检查：团队成员是否真的在使用某份文档（如某个Runbook）？如果没人用，考虑将其归档或删除。
• 可发现性检查：重要的文档是否在README.md或AGENTS.md中有清晰的索引和链接？DECISIONS.md中的ADR索引是否及时更新？

Q8: 如何将这个模板适配到非软件项目（如硬件、写作、研究）？A8: 模板的核心理念——分层管理、上下文固化、对抗审查、过程可观测——是通用的。你需要做的是“翻译”每一层的具体内容：

• 第1层：将“代码注释”变为“设计图纸标注”或“文稿段落旁注”。
• 第2/3层：README变为项目总览，Runbook变为实验操作步骤或写作流程检查单。
• 第4层：ADR变为“实验设计决策记录”或“内容结构决策记录”。
• 第5层：AGENTS.md变为“项目研究背景与目标综述”，CONVENTIONS.md变为“实验规范”或“写作风格指南”。
• 第6/7/8层：工作流、治理和审查机制可以几乎原样保留，只需将里面的术语（如“API”、“编译”）替换为你领域的术语（如“实验参数”、“文稿章节”）。

踩坑实录：在我自己的一个数据分析项目中，最初没有严格区分“人类决策”和“AI建议”。一次，AI在DECISIONS.md中自动“回忆”了一个我们曾讨论但最终否决的技术方案，导致新成员产生了混淆。自那以后，我严格执行了CODEOWNERS保护，并养成了一个习惯：每次与AI讨论完一个决策点，无论采纳与否，我都会亲自去DECISIONS.md或对应的ADR中写下最终结论和简要理由。这多花了一分钟，但避免了后续数小时的沟通成本。

这个模板不是一个要你全盘接受的“铁笼”，而是一套经过实战检验的“乐高积木”。我最深的体会是，在AI时代，项目的成功不仅取决于代码质量，更取决于我们管理“知识”和“上下文”的能力。从这个模板开始，选择最适合你当前团队的几块“积木”搭起来，然后在实践中不断调整、扩展，最终构建出属于你自己的、高效且可靠的AI辅助工程体系。