从零搭建 AI Agent 开发工作流：从一次对话到可持续交付

写给希望让 AI 持续参与开发的个人与团队，也写给将执行这套流程的 AI Agent。

本文使用虚构目录和通用示例，不依赖任何特定项目、业务领域、编程语言或编辑器。文中的模板是一套可迁移的设计，落地时应根据目标仓库的真实结构调整。

1. 先理解：我们要搭建什么

第一次让 AI 修改代码，往往只需要一句话。但持续使用后，问题会逐渐出现：下一次会话不知道上次做到哪里；同类功能使用不同实现；小改动触发大规模重构；AI 说“完成了”，却没有执行验证；修正过的问题又出现。

这些问题需要一套稳定的工作协议。它让 Agent 每次都能回答：

本文把“全 AI Agent 开发工作流”定义为：由 Agent 主动完成需求理解、必要阅读、实现、验证和交付整理，人负责提供业务事实、评估结果并决定需要授权的外部操作。

自动化程度提高，并不意味着业务判断和发布责任消失。文档中的“必须”属于执行约定；脚本只有实际运行才产生检查效果；CI 只有被配置成合并必需检查后，才形成对应的合并约束。

三种角色如何配合

日常使用时，人只需表达需求，无需记住规则文件、选择任务档位或手动触发内部流程。搭建工作流时，则需要把这些职责明确写进仓库。

2. 第一阶段：用三个文件搭出最小闭环

不要一开始创建几十篇规范。先准备一个统一入口、一份执行规则和一个检查脚本：

repository/
├── AGENTS.md
├── agent/
│ └── rules/
│ └── core.md
└── tools/
└── agent/
└── check.sh

上面的路径均为本文示例。目录名可以调整，但入口里的引用必须同步修改。

这三个文件分别回答：去哪里读、按什么顺序做、怎样检查。

2.1 统一入口只负责导航

把以下内容作为根目录 AGENTS.md 的起点：

# Agent 工作入口

适用范围：本仓库中的开发、排查和文档任务。

## 启动顺序

1. 阅读 agent/rules/core.md。
2. 检查当前 Git 状态，识别已有改动。
3. 明确交付物及验收条件，自行判断任务规模。
4. 根据本文件的“已启用规则包”加载适用规则。
5. 阅读直接相关的现有实现后再修改。

## 已启用规则包

暂无。新增时登记触发条件、权威文件与对应检查。

## 验证入口

有文件变更时，由 Agent 执行 bash tools/agent/check.sh。
行为变更还须执行相关构建与测试；命令以仓库配置为准。

## 交付

说明修改结果、验证证据和未完成事项。
未经授权，不提交、推送或发布。
不得覆盖与当前任务无关的已有改动。

入口应保持简短。具体编码规范、数据规则和长模板放到独立文件中，入口只说明何时加载它们。

这里的文件名本身不保证任何工具会自动加载它。需要在所用 Agent 环境中确认入口加载机制；如果没有自动发现能力，就在该环境的启动配置中明确指定读取入口。

2.2 内核只规定通用动作

将以下模板写入 agent/rules/core.md：

# 执行内核

## 开始前

– 明确交付物、验收条件和最小修改范围。
– 检查现有改动，不覆盖他人或其他任务的工作。
– 先读相关实现，再决定如何修改。
– 只询问影响正确性的缺失事实，不要求用户选择工作流档位。

## 执行中

– 采用满足需求的最小正确改动，不顺手重构。
– 任务扩展到新的模块或风险领域时，先加载适用规则。
– 不编造接口、数据关系、测试结果或工具能力。
– 保留仍有效的注释；行为变化时同步修正文档。

## 结束前

– 有文件变更就执行仓库检查入口。
– 根据行为变化执行相关构建、测试或文档检查。
– 必需检查失败时先修复；无法执行时记录原因，不声称通过。
– 交付结果、证据和剩余事项；遵守当前授权范围。

好的规则应有触发条件和可观察动作。“认真检查代码”很难执行，“行为变更时运行相关测试，并报告结果”更具体。

2.3 先让检查入口真正可运行

以下脚本只检查已跟踪改动中的 Git 空白错误，并展示未跟踪文件。它是可运行的起点，不代表代码、业务、安全或未跟踪文件内容已经检查完毕。

写入 tools/agent/check.sh：

#!/usr/bin/env bash
set -euo pipefail

root="$(git rev-parse –show-toplevel)"
cd "$root"

if ! git rev-parse –verify HEAD >/dev/null 2>&1; then
echo "CHECK_STATUS=failed"
echo "REASON=initial_commit_required"
exit 1
fi

echo "CHECK_SCOPE=tracked_changes_against_HEAD"
if ! git diff –check HEAD —; then
echo "CHECK_STATUS=failed"
exit 1
fi

echo "UNTRACKED_FILES_BEGIN"
git ls-files –others –exclude-standard
echo "UNTRACKED_FILES_END"
echo "CHECK_STATUS=passed"
echo "CHECK_COVERAGE=tracked_whitespace_only"

git diff HEAD 比较当前已跟踪文件与当前提交，覆盖其最终状态中的暂存及未暂存改动。未跟踪文件不会自动进入这个 diff，因此必须另行检查，不能把“没有 diff”当成“没有工作需要验证”。

第一次搭建时，让 Agent 创建这三个文件、运行检查，并报告检查范围。随后根据仓库已有配置接入真正的格式检查、类型检查、构建与测试命令。不要照抄与技术栈不符的命令，也不要留下始终成功的测试占位脚本。

**本阶段验收：**给 Agent 一个小改动，它能自己读入口、保护已有工作、修改目标文件、运行检查并说明结果。

3. 第二阶段：让流程随任务规模变化

如果每次改一个文案都阅读整套架构文档，工作流会变成负担。需要让阅读与验证随任务规模变化。

3.1 用五个问题判断任务

Agent 在内部回答：

文件数是参考信号，行为影响同样重要。一行权限判断可能比十个文档文件更需要验证。

3.2 定义三档即可

开始时选择足以完成任务的最小流程。发现范围扩大时再升级，不提前为可能发生的事情创建大量文件。

**任务规模与领域约束分别判断。**修改很少的文件，也不能跳过适用的数据隔离或权限要求。配置变化如果会改变运行行为，也不能仅因扩展名是配置文件就减少验证。

可追加到内核：

## 任务规模

自行选择轻量、单点或完整流程，无需用户确认档位。
阅读与验证按实际影响缩放，领域硬约束始终生效。
范围扩大时，先补读新触发的规则，再继续修改。
纯问答且无文件变化时，不运行无关的交付脚本。

**本阶段验收：**文案修改不会触发全量构建；局部缺陷修复会读取同类实现并执行有意义的相关测试。

4. 第三阶段：把规则拆成内核与规则包

通用流程稳定后，再加入项目适用的知识。可以用四层结构组织：

团队与个人层只能补充适用要求，不能通过一句“跳过检查”关闭硬门禁。此约定仍需执行环境和检查机制配合；文本层级不会自动形成权限隔离。

扩展后的示例结构：

agent/
├── rules/
│ ├── core.md
│ ├── packs/
│ │ ├── data-scope.md
│ │ ├── language.md
│ │ └── migration.md
│ ├── team/
│ └── local/
└── skills/
└── task-start/
└── SKILL.md

4.1 在入口声明已启用规则包

## 已启用规则包

| 包 | 触发条件 | 权威文件 |
|—|—|—|
| data-scope | 查询或修改具有归属边界的数据 | agent/rules/packs/data-scope.md |
| language | 修改应用源代码 | agent/rules/packs/language.md |
| migration | 修改结构或新增数据迁移 | agent/rules/packs/migration.md |

先判断任务语义，再判断文件路径。
规则适用但文件缺失时，查找是否迁移；仍找不到则报告缺口。
不得从缺失文档中推断不存在约束。

仅按文件路径加载可能太晚。例如，Agent 正在设计查询方案，尚未打开数据访问文件，此时数据归属规则已经应该生效。

4.2 一个规则包的可复制结构

以下规则包采用虚构的“工作区数据隔离”场景：

# 数据范围规则

## 触发条件

查询、导出、统计或修改属于某个工作区的数据时适用。

## 必须保持的约束

数据范围来自经过验证的身份上下文。
不得只相信请求参数中的工作区标识。
关联关系必须根据已确认的结构与现有实现确定。

## 实现参考

阅读目标仓库已登记的数据访问样板。
若样板与当前契约冲突，先核实事实再实施。

## 验证

验证当前工作区的数据可访问。
验证其他工作区的数据不可访问。
覆盖实际发生变化的读取、导出或写入路径。

## 例外

跨工作区操作必须具有明确用途、权限边界及验证证据。
不得用一条“允许例外”注释代替权限检查。

## 不确定时

若归属关系或授权范围无法从代码和文档确认，询问业务事实。

规则说明“为什么、何时、怎么做”；脚本或策略配置保存机器判断所需的名单。对同一名单保留一个权威来源，其他文件引用它，避免多份复制逐渐不一致。

4.3 Skill 用来封装重复步骤

当开任务动作经常重复，可将步骤整理为 Skill。其是否自动发现、何时加载，仍取决于 Agent 环境，需要显式适配。

—
name: task-start
description: 开发与排查任务的内部启动流程。
—

# 开任务

1. 阅读仓库入口与内核。
2. 检查 Git 状态，识别已有改动。
3. 明确交付物并判断任务规模。
4. 加载适用规则包。
5. 单点任务读取直接相关的同类实现。
6. 完整任务读取任务路由，选择必要资料。
7. 预计跨会话时，读取或建立对应任务的交接文件。
8. 实施最小正确改动并执行适用验证。

用户无需手动触发本流程。

入口负责导航，规则规定约束，Skill 编排步骤，脚本产生可重复结果。四者分工清楚，后续维护才不会互相覆盖。

**本阶段验收：**任务在动手前加载适用规则；未启用、无关的规则包不会进入上下文。

5. 第四阶段：建立小而可检索的知识库

当 Agent 经常需要理解模块关系时，再补知识库。先写最常用的事实和样板，不追求一次覆盖整个仓库。

docs/engineering/
├── index.md
├── essentials.md
├── task-routing.md
├── patterns/
│ └── endpoint.md
├── domains/
│ └── workspace.md
└── lessons-inbox.md

5.1 先有路由，再增加正文

task-routing.md 示例：

# 任务路由

| 任务 | 先读 | 再看 |
|—|—|—|
| 修改接口 | patterns/endpoint.md | 同模块已验证的相似接口 |
| 调整数据范围 | domains/workspace.md | 适用的数据访问实现 |
| 数据迁移 | 对应迁移规则包 | 最近一个适用迁移样板 |
| 修复缺陷 | 相关模块文档 | 失败路径与已有测试 |

每次先选最相关的一至三份资料；出现具体缺口再扩展阅读。

参考实现也会过期。Agent 应核对它是否仍符合当前契约，不能把“已经存在”理解成“一定正确”。

5.2 每篇知识页回答固定问题

—
title: 工作区数据访问
status: active
verified: YYYY-MM-DD
sources:
– 替换为目标仓库真实的实现路径
—

# 工作区数据访问

## 解决什么问题

## 必须保持的业务事实

## 推荐实现与适用条件

## 常见错误与反例

## 如何验证

## 相关入口

verified 表示最近一次实际核对时间，不能只因编辑了文字就更新。sources 应指向真正核实过的实现，而不是猜测的文件名。

知识库后续可增加三类检查：页面是否进入索引、内部链接是否存在、长期未核验页面是否需要提醒。过期提示通常意味着需要复核，不应自动宣判实现错误。

**本阶段验收：**Agent 能通过路由找到依据，并说明这次选用的样板为何适用。

6. 第五阶段：把约定变成可验证的门禁

“必须遵守”只有被执行和核验后才有实际效果。这里需要区分不同检查的能力。

例如，查询中出现了工作区字段，不等于隔离已经正确实现。它可能来自不可信参数，也可能出现在无效分支中。需要针对真实授权边界设计测试。

6.1 明确检查对象

至少区分三种范围：

已提交但未合并的修改，不能用空的工作区 diff 代替审查。分支检查应记录实际基线；基线不存在或 Git 命令失败时，应明确失败，不能吞掉错误后报告“没有改动”。

对脚本实现的要求：

• 文件列表使用 NUL 分隔等可靠方式，处理空格和特殊字符。
• 纳入未跟踪文件，并处理删除、重命名及二进制文件。
• 按文件类型和完整语法单元选择扫描方式，避免关键词跨文件误匹配。
• 若只扫增量，要说明对未修改上下文的依赖和盲区。
• 将“检查通过”“不适用”“无法执行”“检查失败”分别输出。

6.2 增加统一收尾入口

当检查变多时，用 tools/agent/finish.sh 编排它们。下面是行为契约，尚不是可直接执行的脚本：

确定检查范围和基线
↓
收集已跟踪与未跟踪的变化，识别受影响模块
↓
执行基础检查和适用的领域门禁
↓
执行相关构建、测试、迁移或文档检查
↓
检查是否存在需要记录的新经验
↓
输出每项状态及总体退出码

实现时，必需检查只要有一项失败，总退出码就必须非零。可以继续执行其他独立检查以收集证据，但不要让最后一条成功的输出掩盖前面的失败。依赖失败步骤的检查应标记为阻塞或未执行。

可采用以下机器可读摘要：

AUDIT_SCOPE=working_tree
CHANGED_FILES=3
LINT=passed
BUILD=not_applicable
TESTS=passed
LESSONS_WARNING=no
OVERALL=passed

这只是格式示例，不能原样作为验证结果。not_applicable 需要说明理由；必需检查无法执行时，总体应为 incomplete 或失败，并使用非零退出码。

6.3 用少量反例验证门禁本身

门禁脚本也会写错。至少构造以下验证场景：

这些用例在隔离的临时仓库中执行，避免往工作仓库注入违规样例。

6.4 把同一套检查接入 CI

本地和 CI 应复用核心检查逻辑，分别传入合适的变更范围。CI 还需要配置依赖安装、足够的 Git 历史、目标基线以及对应的构建环境。

推荐的责任分配是：本地快速发现问题，CI 在合并前重新核验。如果某条交付通道没有执行 CI，就不能宣称它拥有相同门禁。Git hook 可以作为可选便利，但不能代替远端必需检查。

**本阶段验收：**故意引入一条已知违规时，本地和 CI 都能按预期失败；修复后通过，且报告相同规则编号。

7. 第六阶段：让跨会话任务可以接续

长任务需要交接文件，因为聊天记录可能被压缩、环境可能切换、执行者也可能变化。

仅为预计跨会话的任务创建状态文件，例如 agent/state/<task-id>.md：

—
task: 替换为明确目标
status: in_progress
updated: YYYY-MM-DD
branch: 替换为实际分支
head: 替换为最后核对的提交标识
—

# 任务交接

## 验收条件

## 已确认事实与决策

## 已完成

## 当前文件变更

## 已运行的验证

记录命令、结果、检查范围，以及验证后是否继续改过代码。

## 未完成与阻塞原因

## 下一步

## 相关文件与依据

续接时先核对任务目标、当前分支、提交与工作区，再使用交接信息。其他任务的 in_progress 文件不意味着应该自动切换过去。

交接保存结论、证据和下一步，不需要复制整段聊天。验证后又改过代码，应重新运行受影响的检查。全部验收条件满足才标记 done。

个人任务状态通常可以加入忽略文件；团队确实需要共享时再纳入版本控制，并避免记录凭据或敏感内容。

**本阶段验收：**新会话能准确说出已完成内容、剩余步骤和验证是否仍有效，不重新执行已确认无须重复的工作。

8. 第七阶段：让错误逐步变成可复用规则

工作流的演进应来自真实问题。每个任务都自动写一篇总结，容易产生重复材料。

只在出现以下信号时记录经验：

• 用户纠正了业务口径、关联关系或权限边界。
• Agent 差点写错，而现有规则和检查无法覆盖。
• 同一种误解反复出现，需要建立统一依据。

lessons-inbox.md 中可使用以下条目：

– 日期：YYYY-MM-DD
现象：跨工作区导出缺少范围校验。
建议：导出路径复用已验证的身份上下文。
证据：替换为实际文件与验证场景。
同类：export-scope
状态：待评估

这是虚构示例。Agent 负责提出有证据的候选经验，负责人评估适用范围，防止把一次特殊处理升级为全局要求。

处理路径可以是：

发现问题 → 记录证据 → 评估是否通用
├─ 业务事实 → 领域文档
├─ 重复步骤 → Skill
├─ 已知反模式 → 规则与检查
└─ 特殊情况 → 保留案例或关闭

同类问题出现两次仍未处理，可以发出提醒。次数阈值只是维护策略，不代表严重程度；单次严重问题也应立即处理。已被检查覆盖的问题无需重复进入收件箱。

**本阶段验收：**至少一条真实经验完成“记录、评估、更新规则或检查、回归验证、关闭”的闭环。

9. 把所有步骤连起来

#mermaid-svg-jEVgyf46gM4LZlgb{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-jEVgyf46gM4LZlgb .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-jEVgyf46gM4LZlgb .error-icon{fill:#552222;}#mermaid-svg-jEVgyf46gM4LZlgb .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-jEVgyf46gM4LZlgb .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-jEVgyf46gM4LZlgb .marker{fill:#333333;stroke:#333333;}#mermaid-svg-jEVgyf46gM4LZlgb .marker.cross{stroke:#333333;}#mermaid-svg-jEVgyf46gM4LZlgb svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-jEVgyf46gM4LZlgb p{margin:0;}#mermaid-svg-jEVgyf46gM4LZlgb .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-jEVgyf46gM4LZlgb .cluster-label text{fill:#333;}#mermaid-svg-jEVgyf46gM4LZlgb .cluster-label span{color:#333;}#mermaid-svg-jEVgyf46gM4LZlgb .cluster-label span p{background-color:transparent;}#mermaid-svg-jEVgyf46gM4LZlgb .label text,#mermaid-svg-jEVgyf46gM4LZlgb span{fill:#333;color:#333;}#mermaid-svg-jEVgyf46gM4LZlgb .node rect,#mermaid-svg-jEVgyf46gM4LZlgb .node circle,#mermaid-svg-jEVgyf46gM4LZlgb .node ellipse,#mermaid-svg-jEVgyf46gM4LZlgb .node polygon,#mermaid-svg-jEVgyf46gM4LZlgb .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-jEVgyf46gM4LZlgb .rough-node .label text,#mermaid-svg-jEVgyf46gM4LZlgb .node .label text,#mermaid-svg-jEVgyf46gM4LZlgb .image-shape .label,#mermaid-svg-jEVgyf46gM4LZlgb .icon-shape .label{text-anchor:middle;}#mermaid-svg-jEVgyf46gM4LZlgb .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-jEVgyf46gM4LZlgb .rough-node .label,#mermaid-svg-jEVgyf46gM4LZlgb .node .label,#mermaid-svg-jEVgyf46gM4LZlgb .image-shape .label,#mermaid-svg-jEVgyf46gM4LZlgb .icon-shape .label{text-align:center;}#mermaid-svg-jEVgyf46gM4LZlgb .node.clickable{cursor:pointer;}#mermaid-svg-jEVgyf46gM4LZlgb .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-jEVgyf46gM4LZlgb .arrowheadPath{fill:#333333;}#mermaid-svg-jEVgyf46gM4LZlgb .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-jEVgyf46gM4LZlgb .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-jEVgyf46gM4LZlgb .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jEVgyf46gM4LZlgb .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-jEVgyf46gM4LZlgb .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jEVgyf46gM4LZlgb .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-jEVgyf46gM4LZlgb .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-jEVgyf46gM4LZlgb .cluster text{fill:#333;}#mermaid-svg-jEVgyf46gM4LZlgb .cluster span{color:#333;}#mermaid-svg-jEVgyf46gM4LZlgb div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-jEVgyf46gM4LZlgb .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-jEVgyf46gM4LZlgb rect.text{fill:none;stroke-width:0;}#mermaid-svg-jEVgyf46gM4LZlgb .icon-shape,#mermaid-svg-jEVgyf46gM4LZlgb .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-jEVgyf46gM4LZlgb .icon-shape p,#mermaid-svg-jEVgyf46gM4LZlgb .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-jEVgyf46gM4LZlgb .icon-shape .label rect,#mermaid-svg-jEVgyf46gM4LZlgb .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-jEVgyf46gM4LZlgb .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-jEVgyf46gM4LZlgb .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-jEVgyf46gM4LZlgb :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

否

是

是

否

失败

无法执行

通过

用户描述需求

读取入口并检查工作状态

明确交付物与验收条件

判断任务规模并加载适用规则

关键事实是否充分

查询依据或询问缺失事实

阅读样板并实施最小改动

范围是否扩大

执行适用验证

必需检查是否通过

报告未完成与具体阻塞

按需更新交接与经验

交付结果和证据

例如，用户提出：“列表页增加一个筛选条件。”

Agent 先确认字段语义与预期结果，读取相似筛选实现。如果影响仅局限于一个模块，就按单点流程执行。如果继续发现接口契约或数据结构必须调整，则补读相关规则并扩大验证范围。修改后覆盖实际改变的筛选行为；若涉及数据归属，还需验证边界。最后交付改了什么、跑了哪些检查、还剩什么。

人的需求没有变成一串工具命令，流程细节由 Agent 承担。

10. 多个 Agent 工具如何共用一套流程

把业务规则保存在仓库中的唯一权威位置，为不同工具建立薄薄的入口适配层。适配层只负责加载，不再复制一整份规范。

接入新工具时验证三件事：

不要仅凭配置文件存在就判断接入成功。让 Agent 报告读取的规则路径、准备修改的范围与验证命令，再用一个小任务检查实际行为。

多 Agent 并行可以后续再引入。先确保单个 Agent 能稳定完成闭环；并行时还需要明确文件所有权、隔离工作区、合并负责人和最终验证责任。

11. 交付信息也要有固定结构

完成回复无需机械粘贴长表，但应包含以下内容：

已完成：具体行为或交付物。

变更：关键文件及修改原因。

验证：实际运行的命令、检查范围与结果。

剩余：未完成事项、无法执行的检查及影响；没有则省略。

“检查通过”必须说明是哪一类检查。“构建通过”不能替代“业务测试通过”。环境限制导致测试未运行时，应明确写出，避免让读者误以为已经验证。

12. 给 AI 的落地执行任务书

以下内容可直接交给目标仓库中的 Agent。它是实施这篇指南的指令模板，不表示前文的示例目录和脚本已经在目标仓库存在。

请为当前仓库搭建一个渐进式 AI Agent 开发工作流。

目标：用户日常只描述需求，Agent 自动完成必要阅读、实现、验证和交付整理。

执行顺序：

1. 检查已有入口、规则、脚本、构建配置和 Git 状态。
优先复用既有机制，不覆盖无关改动，不建立重复规则源。
2. 先搭建统一入口、简短内核和实际可运行的检查入口。
使用仓库真实命令；不能运行的检查明确报告，不写虚假成功占位。
3. 加入轻量、单点、完整三档；档位由 Agent 自判。
领域约束根据任务语义生效，不由文件数量豁免。
4. 只为已确认适用的领域添加规则包，登记触发条件及权威文件。
缺少业务事实时先查已有依据，仍无法确认再询问。
5. 需要时补充最小知识路由、参考样板和交接模板。
不为小任务强制创建专题文档或任务状态文件。
6. 增强检查范围，纳入未跟踪文件，并区分工作区与分支审计。
基线缺失、工具缺失和检查失败均不得解释成通过。
7. 为门禁设计合法、违规、未跟踪文件和错误基线等验证场景。
在隔离临时环境运行，检查退出码和定位结果。
8. 若已有 CI，则复用核心检查接入当前流程。
若需要外部配置或授权，先完成本地可审阅产物，再说明剩余步骤。
9. 提供经验收件箱，仅记录真实且尚未覆盖的问题。
10. 交付实际文件、检查证据、覆盖边界与尚未完成的配置。

约束：

– 不假设任何工具自动识别所有规则格式，必须验证入口加载。
– 不引入与仓库无关的技术栈、业务名单和平台规范。
– 团队与个人补充不能关闭适用硬门禁。
– 不为工作流完整而重构业务代码。
– 不擅自提交、推送或发布，遵守当前明确授权。

完成条件：

一次普通需求能实际走通：入口读取 → 必要阅读 → 修改 → 验证 → 交付。
文档承诺的自动动作，应有实测证据；尚未实现的能力明确列为后续项。

13. 最终验收：检查工作流是否真的成立

可以分三轮建设：第一轮跑通最小闭环；第二轮加入实际用到的领域规则、样板和行为验证；第三轮再完善分支门禁、交接与经验维护。每轮都用真实的小任务验收，再增加下一层能力。