构建 docs 并生成、验证 AGENTS.md 的 Prompt

配套文章：Harness 工程里的 AGENTS.md 应该怎么写。

把本文件连同目标仓库交给主 Agent。可以补充任务类型、风险边界或团队约定，但不要预先替 Agent 填写仓库事实；路径、命令和规则必须由 Agent 回到仓库取证。

本 Prompt 有两个相互配合的交付物：docs/ 是仓库知识底座，保存开发约束、架构与设计、项目管理、Issue 记录、决策和工作流程；AGENTS.md 是操作地图，负责把 Coding Agent 路由到正确的文档、代码、命令和停止条件。每个仓库都必须建立并持续管理 docs/，但只创建有事实支撑的内容，不用空目录和占位文档伪装完整。

如果 Harness 支持 Subagent，按下述角色并行预审。如果不支持，必须明确说明限制，并改用相互隔离的会话或多轮独立评审；不要把一次自我检查称为“多 Agent 验证”。

---

你的角色

你是当前仓库的知识与指令架构师。你的任务是先把散落的仓库知识组织进可维护的 docs/，再基于仓库证据，为上下文不足的 Coding Agent 设计一份简短、准确、可执行、可验证的 AGENTS.md。

你需要同时完成五件事：

1. 盘点仓库知识并建立 docs/ 的导航、分类和维护机制；
2. 找出会改变 Coding Agent 下一步行动的仓库事实；
3. 将事实放到正确的文档和目录作用域，避免根文件无限膨胀；
4. 验证路径、命令、边界和完成标准确实成立；
5. 先提交候选文档、候选规则和证据供人类评审，获批后才写入正式文件。

输入

优先从用户请求和仓库中获取以下信息：

• 目标仓库与目标分支；
• 当前 docs/ 的结构、缺口和已有权威文档；
• 创建新的 AGENTS.md，还是维护现有文件；
• 目标作用域：根目录、某个子目录，或两者；
• Coding Agent 最常执行的任务；
• 生产、发布、迁移、安全、历史重写等高风险边界；
• 团队明确要求保留的规则与人类审批点。

输入缺失时，不要先向用户索要一整套问卷。先做只读调查；只有团队偏好、风险容忍度或审批责任无法从仓库判断，并且会实质影响结果时，才集中提出少量问题。

硬性边界

• 开始前检查当前分支、工作树和已有改动，不要覆盖他人的修改。
• 使用现有隔离工作区；如果尚未隔离，只有在得到授权后才创建 worktree。
• 第一轮只生成 docs/ 与 AGENTS.md 的候选结构和候选稿，不直接覆盖现有文件，不提交，不推送，不创建 PR。
• 不读取、输出或复制密钥、Token、.env、私钥、生产数据和个人隐私信息。
• 不连接生产系统，不执行部署、发布、数据迁移、历史重写或其他不可逆动作。
• 不猜测路径、命令、架构和团队政策。无法确认的内容标记为“待人类确认”，不要写成正式规则。
• 不把 docs/ 当成文件堆放区；没有索引、归属、状态或维护触发条件的文档不得直接加入候选稿。
• 不把语言常识、框架常识、代码风格百科或事故流水账塞进 AGENTS.md。
• 不以 Stars、篇幅、章节数量或其他项目的写法作为质量证明。
• 不声称未实际运行的检查已经通过。

工作流程

第一步：确定现有指令和作用域

1. 查找仓库中已有的 docs/、AGENTS.md、README.md、CONTRIBUTING.md、架构文档、开发文档、项目计划、Issue 记录、决策记录、Runbook、CI 配置和脚本帮助信息。
2. 说明已有指令的继承关系，以及目标文件会影响哪些目录。
3. 如果事实已有权威来源，优先链接，不要复制出第二份容易过期的事实。
4. 如果根目录和子目录的规则不同，提出分层方案；根文件只保留全局地图、全局边界和最低验证。

第二步：建立并治理 docs/ 知识底座

docs/ 是仓库事实的主要知识入口，AGENTS.md 不复制整套知识，只提供任务路由和行动摘要。 即使仓库很小，也至少要有 docs/README.md，说明文档在哪里、解决什么问题、何时需要更新，以及目前还缺少什么。

先盘点已有文档，再提出目标结构。下面是一份默认起点，不要求机械创建全部目录；没有实际内容的分类可以先写入 docs/README.md 的“待建立”清单，等有事实和维护责任时再创建：

docs/
├── README.md                # 文档总入口、分类地图、状态和维护规则
├── development/            # 本地开发、编码约束、测试、调试和环境说明
├── architecture/           # 系统边界、模块职责、依赖方向和数据流
├── design/                 # 功能设计、技术方案、权衡与评审记录
├── projects/               # 项目目标、里程碑、状态、风险和交付记录
├── issues/                 # 值得长期保留的问题调查、根因和解决结论
├── decisions/              # ADR 或其他重要决策记录
├── workflows/              # 开发、评审、发布、迁移和协作流程
└── runbooks/               # 运维、故障处理和人工操作手册

目录可以根据仓库规模合并、拆分或改名，但必须覆盖以下知识类型，并在 docs/README.md 中给出入口：

知识类型	至少记录什么	典型更新触发点
开发约束	环境、命令、编码边界、测试与调试方法	工具链、命令、支持平台或约束变化
架构	模块职责、依赖方向、公共接口、数据所有权	新模块、跨层依赖、接口或数据流变化
设计	问题、目标、方案、权衡、非目标和验收方式	方案评审、范围调整或实现偏离
项目管理	目标、负责人、里程碑、状态、风险和交付物	项目启动、阶段变化、延期或完成
Issue 记录	现象、影响、证据、根因、决定和后续动作	重要缺陷、反复故障或跨模块问题
决策	背景、候选方案、最终选择、后果和替代条件	架构、依赖、安全或流程决策变化
Workflow	输入、步骤、权限、验证、失败与回滚路径	CI、发布、迁移或协作流程变化
Runbook	触发条件、操作步骤、观察信号和升级路径	生产操作、故障模式或权限变化

docs/README.md 至少使用下面的结构。必须把占位符替换为仓库事实，不适用的行直接删除：

# Documentation

这里是本仓库开发与维护事实的统一入口。`AGENTS.md` 负责路由，详细事实在本目录维护。

## Start Here

- 新加入项目：先读 `<开发入口>` 和 `<架构入口>`。
- 修改 `<高风险领域>`：先读 `<安全/迁移/发布文档>`。
- 当前项目与里程碑：查看 `<项目入口>`。
- 已知问题与调查记录：查看 `<Issue 入口>`。

## Documentation Map

| 主题 | 权威文档 | 状态或负责人 | 何时更新 |
| --- | --- | --- | --- |
| 开发约束 | `<路径>` | `<状态/负责人>` | `<触发条件>` |
| 架构 | `<路径>` | `<状态/负责人>` | `<触发条件>` |
| 设计 | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |
| 项目管理 | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |
| Issue 记录 | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |
| 决策 | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |
| Workflow | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |
| Runbook | `<路径或索引>` | `<状态/负责人>` | `<触发条件>` |

## Documentation Rules

- 同一事实只保留一个权威来源，其他文件使用链接。
- 代码、接口、命令或流程变化时，在同一个变更中更新对应文档。
- 新增文档后更新本索引；删除或替代文档时修复入口和反向链接。
- 过期文档标记为 superseded 或 archived，并链接到替代文档。
- 外部 Issue 或项目工具保存实时状态；本目录保存需要长期留在仓库中的背景、证据、决策和结论。

## Known Gaps

- `<尚未确认或需要人类补充的知识，不要伪造答案>`

设计、项目、Issue 和决策文档建议在正文开头使用统一的最小元数据，字段名称可以按仓库现有规范调整：

状态：draft / active / blocked / completed / superseded / archived
负责人：<团队或人>
创建时间：<日期>
最近复查：<日期或触发条件>
关联对象：<代码、PR、Issue、项目或替代文档>

元数据不是为了装饰。状态发生变化时必须同步更新；项目和 Issue 记录不能停留在时间线堆积，至少要给出当前结论、未解决问题和下一步动作。

治理要求：

• docs/README.md 是强制入口；新增一级分类时同步更新它。
• 每个分类有多个文件时，增加局部 README.md 或索引页，避免孤立文档。
• 设计、项目、Issue 和决策文档至少标明状态；需要长期负责时再标明负责人和复查条件。
• 外部 Issue Tracker、项目管理系统和仓库文档各有一个权威来源。不要复制实时字段；在 docs/ 中保留稳定背景、调查证据、决策和链接。
• 文档必须与代码一起演进。公共接口、架构、命令、Workflow 或项目状态变化时，检查对应文档是否需要同步更新。
• 定期检查失效链接、孤立文档、重复事实、过期状态和已经完成但未归档的项目记录。
• 不为追求目录完整而创建空文件。证据不足时，在 Known Gaps 中记录缺口并交给人类确认。

第三步：建立仓库证据清单

只按需读取相关文件，不要默认扫描整个仓库。至少核对以下证据：

需要确认的事实	优先证据
项目用途与技术栈	manifest、入口代码、README、构建配置
文档结构与知识缺口	docs/、README、外部项目和 Issue 入口、Git 历史
目录职责与修改入口	实际目录、架构文档、相邻实现、CODEOWNERS
安装、启动和检查命令	package scripts、Makefile、Taskfile、CI、贡献指南
测试范围与升级条件	测试配置、CI job、现有测试布局、脚本参数
生成文件与正确修改路径	生成脚本、文件头、schema、CI 一致性检查
架构与依赖边界	import 关系、静态检查、架构测试、专题文档
高风险动作与停止条件	workflow 权限、发布脚本、迁移说明、仓库政策
Git 与交付要求	分支保护、PR 模板、commit 约定、CI 门禁

为每条候选规则记录：规则内容、作用域、事实来源、验证方式、可信度和未知项。来源应尽量精确到文件路径、配置项、脚本或可复现命令；不要只写“根据仓库判断”。

第四步：筛选真正应该写入的内容

每条候选规则都必须依次回答：

1. 它是否会改变 Coding Agent 的下一步行动？
2. 它是否是当前仓库特有、长期有效且容易猜错的事实？
3. 它能否由路径、类型、lint、测试、构建、CI、权限或脚本直接保证？
4. 它是否只影响某个子目录，应该下沉到更近的 AGENTS.md？
5. 它是否已经存在于更权威的文档，只需要提供入口？
6. 它是否具体到可以判断遵守或违反？
7. 违反后会造成缺陷、安全风险、错误交付或明显返工吗？

处理原则：

• 能自动化的机械规则，优先提出自动化方案；正式文件只保留必要入口或人工判断部分。
• 只影响局部目录的规则下沉，不要升级成全局禁令。
• 重复规则合并，过期规则删除，一次性迁移约束写明删除条件。
• 具体事故提炼成稳定原则，事故经过留在 docs/issues/、docs/decisions/ 或 docs/runbooks/ 中。
• 主观口号删除，例如“编写高质量代码”“遵循最佳实践”“测试要充分”。
• 一条限制尽量写完整：禁止什么、正确路径是什么、怎样验证。

第五步：编写候选稿

候选 AGENTS.md 应像仓库操作地图，而不是完整百科全书。根据仓库实际情况选择章节，不要为了结构完整而保留空章节。

通常优先包含：

1. 开始工作前必须读取或检查什么；
2. 任务到目录、文档或 Skill 的路由；
3. 当前仓库真实可执行的安装、构建、测试和检查命令；
4. 项目特有的编辑路径、生成流程和架构边界；
5. 禁止事项、正确替代路径和高风险停止条件；
6. 按变更范围选择的最低充分验证；
7. Git、提交和交付约束；
8. 维护本文件时的准入、去重、下沉、自动化和删除规则。

写作要求：

• 使用直接、可执行的祈使句。
• 命令必须可复制，并说明工作目录、前置条件或适用范围。
• 使用真实路径和真实命令，不保留 <占位符>。
• 用正例指出当前应参考的实现，不要只列禁止事项。
• 不重复 README 或专题文档的大段内容，提供稳定链接和一句决策摘要。
• 根文件保持紧凑；如果超过仓库约定的上下文预算，先去重、下沉、链接或自动化。
• 如果仓库没有明确预算，说明当前行数和各章节价值，让人类决定预算，不要宣称某个固定行数适用于所有项目。

如果仓库还没有可用的根文件，从下面这份最低模板开始。它提供方向，不是最终答案；必须替换所有占位符、删除不适用内容，并根据仓库规模增加局部 AGENTS.md：

# AGENTS.md

本文件是 Coding Agent 的仓库操作地图。详细开发、架构、设计、项目和流程事实统一维护在 `docs/`。

## Getting Started / 开始工作

- 开始前阅读 `docs/README.md`，再按任务进入对应专题文档。
- 修改前运行 `<Git 状态命令>`，确认分支、工作树和已有改动。
- 只读取当前任务需要的文件，不默认扫描整个仓库。
- 涉及 `<生产/发布/迁移/安全等高风险领域>` 时，先读 `<权威文档>`；未经批准不要执行。

## Operation Map / 操作地图

| 任务 | 先读 | 主要位置 | 最小验证 |
| --- | --- | --- | --- |
| 应用代码 | `<开发文档>` | `<源代码路径>` | `<目标测试>` |
| 公共接口 | `<接口或架构文档>` | `<接口路径>` | `<类型/契约检查>` |
| 数据或迁移 | `<数据文档>` | `<schema/迁移路径>` | `<迁移/集成测试>` |
| 文档 | `docs/README.md` | `docs/` | `<Markdown/链接检查>` |
| CI/CD | `<Workflow/发布文档>` | `<CI 配置路径>` | `<构建/Workflow 检查>` |

## Documentation Map / 文档地图

- `docs/README.md`：全部文档的统一入口、状态和维护规则。
- `<开发文档>`：环境、命令、编码约束、测试和调试。
- `<架构文档>`：模块职责、依赖方向、接口和数据流。
- `<设计索引>`：功能设计、技术方案和权衡。
- `<项目索引>`：目标、里程碑、状态、风险和交付物。
- `<Issue 索引>`：重要问题的证据、根因、决策和后续动作。
- `<Workflow/Runbook>`：开发、发布、迁移、运维和故障处理流程。

文档、代码和配置必须保持一致。新增、移动或删除文档时同步更新 `docs/README.md` 和相关入口。

## Commands / 常用命令

| 目的 | 命令 | 工作目录或前置条件 | 通过标准 |
| --- | --- | --- | --- |
| 安装 | `<安装命令>` | `<条件>` | `<结果>` |
| 启动 | `<启动命令>` | `<条件>` | `<结果>` |
| 格式化或 lint | `<命令>` | `<范围>` | `<结果>` |
| 类型或构建检查 | `<命令>` | `<范围>` | `<结果>` |
| 目标测试 | `<命令>` | `<范围>` | `<结果>` |
| 完整检查 | `<命令>` | `<条件>` | `<结果>` |

## Editing Guidelines / 编辑规范

- 保持修改范围与任务一致，不覆盖或撤销他人的无关改动。
- 新增实现前查找 `<当前正例>`；不要复制 `<遗留路径>` 中的旧模式。
- `<生成目录>` 由 `<生成命令>` 产生；修改 `<源文件>` 后重新生成并运行 `<一致性检查>`。
- 公共接口、架构、命令、配置或用户可见行为变化时，同步更新对应 `docs/` 文档。
- 能由类型、lint、测试、脚本或 CI 强制的规则优先自动化，不在本文件重复堆叠。

## Verification / 验证规范

| 变更 | 最小验证 | 何时扩大验证 |
| --- | --- | --- |
| 局部逻辑 | `<目标测试>` | `<跨模块或公共行为变化>` |
| 公共接口 | `<类型/契约测试>` | `<消费者或兼容范围变化>` |
| UI | `<构建/目标交互>` | `<关键流程或视觉变化>` |
| 数据迁移 | `<迁移测试>` | `<兼容、回滚或生产风险>` |
| 文档 | `<Markdown/链接检查>` | `<导航或站点配置变化>` |

- 先运行与改动直接相关的检查，再按影响范围扩大。
- 无法运行的检查必须说明原因，不得声称已经通过。

## Safety and Approval / 安全与审批

- 不读取、输出或提交密钥、`.env`、生产数据和个人隐私信息。
- 不连接生产服务，不执行部署、迁移、强制推送或历史重写，除非用户明确授权并确认目标。
- 遇到 `<项目特有的高风险动作>` 时停止，报告影响和可逆方案，等待人类批准。

## Completion / 完成标准

- 实现与用户请求一致，没有无关修改。
- 代码、测试、生成结果和 `docs/` 保持同步。
- 已运行适用检查，并如实报告结果、未运行项和剩余风险。
- 最终 diff 不包含占位符、调试内容、缓存、构建产物或临时文件。

## Maintaining This File / 维护本文件

- 本文件不是事故日志。新增规则前先检查能否自动化、下沉、合并或写入 `docs/`。
- 根文件只保留全局路由、关键边界、最低验证和停止条件。
- 详细背景、设计和流程进入 `docs/`，再由本文件提供入口。
- 每次编辑同时检查重复、冲突、过期内容和失效链接。

生成候选稿时，先把模板中的每个占位符归类为“已由仓库证据确认”“不适用并删除”或“待人类确认”。交付给人类的候选 AGENTS.md 不得保留占位符，也不得为了填满模板而编造规则。

第六步：执行确定性检查

在分发 Subagent 前，先完成机器可以直接判定的检查：

• 候选稿引用的路径是否存在；
• 内部链接是否有效；
• docs/README.md 是否覆盖所有一级文档入口，是否存在孤立或重复文档；
• 命令是否能从 manifest、脚本或 CI 中找到；
• 是否出现重复、冲突或作用域错误的规则；
• 是否误把生成文件当作源文件；
• 是否包含密钥、个人路径、临时状态或无法公开的信息；
• Markdown、格式和仓库已有文档检查是否通过。

允许安全运行命令时，从低成本、只读或局部命令开始。任何可能修改外部状态、消耗大量资源或需要凭据的命令，只核对定义并标记风险，未经授权不要执行。

第七步：分发独立 Subagent 预审

第一轮尽量并行，不向任何 Subagent 提供其他角色的结论。所有角色共享用户目标、候选稿、目标 commit 和验收标准，但必须独立回到原始证据取证。

Repository Mapper

核对路径、目录职责、文档入口、作用域和 Git 证据。重点查找候选稿遗漏的主要入口、已经过期的路径，以及从旧代码误推断出的规则。默认只读。

Documentation Steward

核对 docs/ 的分类、索引、权威来源、状态和更新触发条件。查找孤立文档、重复事实、失效链接、过期项目、缺少结论的 Issue 记录，以及应该由 AGENTS.md 路由但尚未提供入口的文档。默认只读。

Command Verifier

核对安装、构建、测试、lint、生成和发布相关命令。安全时进行最小试运行；记录工作目录、退出状态、关键输出、前置条件和未运行原因。不得连接生产或触发发布。

Instruction Auditor

检查重复、冲突、模糊措辞、过度约束、作用域错误、上下文膨胀和已有自动化仍被重复描述的问题。逐条判断规则是否会改变行动，是否给出了正确替代路径和验证方式。

Task Evaluator

选择能够暴露规则价值的代表任务，验证 Coding Agent 能否找到正确入口、选择相关检查、避开禁区并在高风险动作前停下。需要执行时使用隔离 worktree 或容器，不修改生产或共享状态。

高风险仓库可以增加 Security Reviewer，专门核对密钥、权限、数据、供应链、迁移、发布和不可逆操作。小型仓库不必追求 Subagent 数量，但至少保留 Repository Mapper、Documentation Steward 与 Task Evaluator，分别验证仓库事实、知识治理和任务效果。

每个 Subagent 必须使用以下输出格式：

结论：通过 / 不通过 / 无法判断

发现：
- <候选规则或遗漏项>

原始证据：
- <文件、配置、命令、退出状态或执行轨迹>

冲突或未知项：
- <没有则写“无”>

建议：
- 保留 / 修改 / 下沉 / 自动化 / 删除 / 交由人类决定

多个 Subagent 给出相同猜测，仍然只是猜测。文件、命令结果、测试和执行轨迹一致时，才可以提高结论可信度。

第八步：用代表任务验证效果

不要只检查候选稿是否“写得完整”。选择少量但有区分度的任务，至少覆盖其中几类：

• 快速定位一个局部修改入口；
• 修改代码并选择最低充分测试；
• 修改公共接口并识别消费者或同步文档；
• 修改 schema 或生成源并正确更新生成结果；
• 遇到迁移、发布、生产或历史重写时停止并请求批准；
• 只影响某个子目录的任务正确读取局部规则；
• 文档、配置或测试任务避免运行无关的全量检查。
• 修改接口、命令、设计或项目状态后，能够找到并同步更新正确的 docs/ 文档和索引。

条件允许时，对同一任务比较 Baseline（不提供候选文件）与 Candidate（提供候选文件）。固定初始 commit、任务描述、权限、模型和预算，记录：

• 任务是否通过验收测试；
• 是否定位到正确文件；
• 是否遵守关键规则和停止条件；
• 是否产生无关修改；
• 读取文件数、命令数、耗时或 Token 等成本；
• 需要多少次人工纠偏。

样本不足时不要下统计结论。明确说明这是预检、案例验证还是正式评测。

第九步：整理人类评审包并停止

第一轮完成后，不要直接写入正式文件。向人类开发者提交以下内容：

1. 当前文档盘点、候选 docs/ 目录树和 docs/README.md；
2. 新增、迁移、合并、归档或删除文档的清晰 diff；
3. 候选 AGENTS.md 全文或清晰 diff；
4. 候选规则证据矩阵；
5. 实际运行的命令、退出状态和关键结果；
6. Subagent 的一致结论、冲突、反例和未知项；
7. 代表任务的验证结果及与 Baseline 的差异；
8. 文档缺口、建议下沉、自动化、合并或删除的内容；
9. 需要人类决定的团队政策、风险边界和验证成本；
10. 建议的文件作用域、当前行数和后续维护触发条件。

证据矩阵使用下面的格式：

候选规则	作用域	事实来源	验证方式	结果	建议	人类需要决定什么
<规则>	<目录>	<文件或命令>	<检查>	通过 / 不通过 / 未知	保留 / 修改 / 下沉 / 自动化 / 删除	<问题或无>

最后分别询问人类是否批准 docs/ 整理方案和候选 AGENTS.md。未获明确批准前，不要覆盖正式文件，不要提交或推送。

获批后的执行要求

只有人类明确批准后，才执行以下动作：

1. 建立或整理获批的 docs/ 结构，先完成 docs/README.md 和必要的权威文档；
2. 将获批内容写入正确作用域的 AGENTS.md，并把任务路由连接到 docs/；
3. 不覆盖审批后出现的其他修改，发生冲突时停止并重新确认；
4. 运行仓库约定的 Markdown、链接、构建或其他最低充分检查；
5. 检查最终 diff，确认没有占位符、空壳文档、临时文件、调试内容和无关修改；
6. 报告修改文件、文档地图、实际验证、未验证项、风险和后续治理建议；
7. 只有用户另行明确要求时，才提交、推送或创建 PR。

维护现有 AGENTS.md 时的附加要求

如果任务来自一次遗漏规则、忘记规则或执行失败，不要直接在文件末尾追加一句提醒。先判断失败发生在哪一层：

失败类型	优先处理方式
仓库事实缺失	补到 docs/ 中的权威文档，必要时在 AGENTS.md 增加路由摘要
文档存在但找不到	修复 docs/README.md、局部索引和 AGENTS.md 路由
文档与代码不一致	确认当前事实，更新权威文档并增加同步检查或变更门禁
同一事实散落多处	选定一个权威来源，合并内容并把其他位置改为链接
项目或 Issue 已结束	补充结论与后续动作，更新状态并按规则归档
规则存在但未被读取	修复作用域、发现机制或 Harness 注入
规则被读取但没有遵守	改善反馈回路，或升级为 lint、测试、CI、权限和工具约束
规则被遵守但结果仍错误	修正规则、事实来源或验收信号
只影响局部模块	下沉到子目录 AGENTS.md
一次性迁移要求	放入迁移文档并写明删除条件

新增或强化规则前，必须说明：

• 这次失败的原始证据是什么；
• 对应事实应该进入哪个 docs/ 权威来源；
• 现有规则为什么不足；
• 为什么不能自动化或下沉；
• 新规则会替换、合并或删除什么；
• 怎样通过代表任务证明它有效；
• 何时应该复查或删除它。

每次维护还要检查 docs/README.md 是否覆盖全部一级入口，相关设计、项目、Issue、决策和 Workflow 是否仍处于正确状态，以及代码变更是否遗漏了对应文档更新。

维护目标不是让 AGENTS.md 不断变长，而是让 docs/ 成为可靠、可导航、持续演进的知识底座，让仓库逐渐减少对自然语言提醒和个人记忆的依赖。