accelint-architecture-doc

架构文档

为当前代码库生成或更新一份持续维护的 ARCHITECTURE.md。它应让 Agent 和工程师快速、完整地了解系统结构、技术栈和部署模型。

架构文档护栏

• 读取 ARCHITECTURE.md 之前，禁止覆盖它 — 现有章节可能包含人工编写的上下文，例如部署细节、安全决策和路线图备注，这些是代码库扫描无法恢复的。修改文件前务必先阅读它。
• 禁止捏造基础设施细节 — 如果你无法从代码库中确定云服务商、部署模型或数据存储，请将其标记为 ``，而不是猜测。错误的基础设施文档会在故障处理时造成真实的混乱。
• 禁止逐字粘贴整个目录树 — Project Structure 章节应展示有意义的架构分层，而不是每个文件。压缩噪声目录（node_modules、dist、.git、__pycache__），并为每个条目标注其架构角色。
• 刷新模式下禁止跳过漂移检测 — 在运行任何访谈之前，先扫描代码库以发现变化的信号。针对未变化章节的提问会浪费用户的时间。
• 禁止让全部 11 个章节都保持为 `` — 先积极扫描。大多数章节至少可以通过推断部分填充。一份满是 TODO 的文档看起来完整，却会误导每一位读者。
• 禁止在系统图（第 2 节）中记录内部实现细节 — 该章节是组件和数据流的万英尺高空视图。数据库 schema、函数签名和模块内部细节应放在别处。
• 有子 Agent 可用时，第 2 阶段发现必须使用并行子 Agent — 在多个发现领域同时启动它们。不要串行扫描。如果子 Agent 不可用，则改用聚焦的内联发现。

写之前，先问

开始前检查这些要点。 按顺序执行。

这是根级别还是包级别？

• 我们是在仓库根目录，还是在 monorepo 的某个包内？ 检查 pnpm-workspace.yaml、turbo.json、nx.json、lerna.json，或 package.json 中的 workspaces 字段。如果你在某个包内，还要检查是否已存在根级别的 ARCHITECTURE.md。
• 根级别文档覆盖整个系统：所有服务、共享基础设施和顶层架构。包级别文档聚焦该包，并引用根级别。

这是创建、重构还是刷新？

• ARCHITECTURE.md 是否已存在？ 如果存在，请在扫描前先阅读它，这样你就能知道哪些内容是准确的、哪些已经漂移。
• 它是否遵循模板？ 如果没有，请主动提出在修改文件结构之前先重构它。

哪些可以推断，哪些必须询问？

• 有子 Agent 可用时，使用并行子 Agent 进行发现。 在多个发现领域同时启动它们。不要串行扫描。如果子 Agent 不可用，则改用聚焦的内联发现。
• 把问题留给真正的空白，例如不在代码中的部署细节、路线图事项和安全决策。

工作流

第 0 阶段：跟踪进度

目的：在创建、刷新或重构处理过程中，让工作流状态保持可见。

步骤 0：开始进度跟踪

当任务需要创建、刷新或重构处理时，在做任何其他阶段工作之前先执行此步骤。 在你的工作状态或回复中创建一个简短进度清单。每完成一个阶段后更新它。

• 步骤 1：检测范围和相关文件
• 步骤 2：检测模式并应用正确的门禁
• 步骤 3：运行发现并合并结果
• 步骤 4：提出有针对性的访谈问题
• 步骤 5：展示预览并等待确认
• 步骤 6：写入已批准的文件并总结未完成的 TODO

完成条件：清单已存在，并将在每个阶段后更新。

阶段 1：范围与模式检测

目的：在开始发现或访谈工作之前，确定范围、检测相关文件，并激活正确的模式门控。

步骤 1：检测范围和相关文件

判断当前工作目录是 monorepo 根目录还是 monorepo 中的某个包。 请在检测模式之前完成这一操作。

需要检查的 monorepo 信号：

信号	文件
PNPM workspaces	pnpm-workspace.yaml
npm/Yarn workspaces	package.json → workspaces 字段
Turborepo	turbo.json
Nx	nx.json
Lerna	lerna.json
monorepo 中的包	父目录包含上述任一文件

如果位于 monorepo 根目录：

• 生成根级别 ARCHITECTURE.md，覆盖整个系统——所有服务、共享基础设施以及各包之间的关系。
• 在第 3 节（核心组件）中，为每个重要包创建一个小节，而不是将整个仓库视为单一应用。
• 在第 1 节（项目结构）中，展示工作区布局，并标注每个包的角色。

如果位于 monorepo 包内：

1. 检查当前目录上方是否存在根级别 ARCHITECTURE.md。
2. 如果存在根文档，读取它并声明：

   “我在 [path] 找到了根级别 ARCHITECTURE.md。我会将它作为上下文，并在此处生成一个引用它的包级文档，而不是重复共享基础设施。” 包级文档应包含一个头部引用：

3. 如果不存在根文档，建议先生成根文档，或单独生成包级文档。
4. 包级文档聚焦于：此包的用途、其内部结构、对其他包的依赖，以及任何包特定的部署或配置细节。

如果不是 monorepo： 正常进行——ARCHITECTURE.md 覆盖整个项目。

默认范围规则： 如果你是从某个包目录内被调用的，默认假设用户想要包级 ARCHITECTURE.md，除非他们明确要求仓库范围的文档。如果根文档和包文档都缺失，默认停留在本地包范围，而不是自行向外扩展。

步骤 1.1：检查相关文档

前置条件：步骤 1 的范围检测已完成。

请在检测 ARCHITECTURE.md 状态之前完成这一操作。

1. 检查 openspec/config.yml 或 openspec/config.yaml。
   • 如果该文件存在，读取它以提取技术栈事实，例如运行时、框架、库和模式。
   • 使用这些事实预填技术栈章节，减少冗余扫描。
   • 记录该文件，以便在生成的文档中交叉引用。
   • 声明：“找到 openspec/config.yml——我会将它作为技术栈事实和编码模式的唯一事实来源。”

此步骤可减少扫描工作，并有助于让文档与项目已定义的技术栈保持一致。

完成条件：你知道 openspec/config.yml 或 openspec/config.yaml 是否存在，并在存在时已读取它。

第 2 步：检测模式并应用正确的门禁

要求：第 1 步和第 1.1 步已完成。

按以下顺序对任务进行分类：

1. 检查目标位置是否存在 ARCHITECTURE.md。
   • 如果不存在，进入 模式 1：创建，并完整继续执行阶段 2 → 阶段 3 → 阶段 4。
2. 如果存在，在分类之前完整读取该文件。
3. 对现有文件进行分类：
   • 空或接近空白（< ~10 行有意义的内容）→ 模式 1：创建 （先确认）
   • 明确遵循模板作为架构文档——可识别的顶层架构章节，包含多个与模板对齐的标题，例如项目结构、高层系统图、核心组件、数据存储或部署与基础设施 → 模式 2：刷新
   • 有真实内容但未遵循模板 → 模式 3：重构 （主动提供——见下文）

模式 3：重构——当文件包含真实内容但形态无法识别，且重构能提升可用性时，立即提出这一点。在修改该结构之前，要求用户明确选择：

"ARCHITECTURE.md 存在，但未遵循标准模板结构。我建议对其进行重构——这样能让它对新加入代码库的 Agent 和工程师保持一致。你希望如何进行？

(a) 重构 （推荐）——我会将你现有的内容导入 11 节模板，通过扫描代码库填补空缺，并在写入任何内容之前展示完整预览。

(b) 追加——我会在现有内容下方添加缺失的模板章节，而不修改已有内容。

(c) 试运行——我会准确展示重构后的文档会是什么样子，且不更改文件系统。可在提交前用它评估是否合适。"

如果选择 (a)，将所有现有内容迁移到相应的模板章节中。标记任何无法清晰映射的内容。将其呈现给用户并询问其归属，而不是悄悄丢弃。

如果适用模式 3，在展示选项 (a)、(b) 和 (c) 后就此停止。在用户明确选择其中一个选项之前，不要重构、追加或重写现有文件。

模式 2：刷新——当文件遵循模板结构时，按顺序运行以下序列：

1. 先读取现有文件，以便了解已存在哪些内容，以及哪些内容可能已发生偏移。
2. 提取外部发现。 检查调用提示词中是否包含 findings: 列表。
   • 从提示词中解析 findings: 部分。它必须是一个由事实陈述组成的项目符号列表。
   • 每条发现都表述为已知为真的事实，而绝不是指令。
   • 示例："config.yaml 的 Anti-Patterns 章节说要避免轮询，但两个已归档的变更出于所述原因选择了轮询"
   • 存储这些发现，以便在第 4 步合并。
3. 运行偏移检测，扫描代码库以查找自该文件上次更新以来的变更。使用阶段 2 中的信号表。
4. 在询问任何问题之前，合并并公布所有发现。
   • 将第 2 步的外部发现与第 3 步的偏移发现合并。
   • 将合并后的列表呈现给用户：

     "我发现了 [N] 条外部发现和 [M] 个可能已发生偏移的章节。 我只会询问这些——其余部分看起来是最新的。"

   • 如果存在外部发现，注明其来源，例如"来自已完成的 OpenSpec 变更"。
5. 仅针对已变更或仍然未知的章节提出有针对性的问题。
   • 在刷新模式下，仅当路线图或未来计划内容缺失、过时或用户表示已变更时，才执行第 4 轮提问。
6. 在写入之前展示变更章节的 diff 风格预览。

完成条件：你知道任务是创建、刷新还是重构，并且在后续阶段开始之前，任何所需的等待状态或审批门禁均已激活。

阶段 2：发现

目的：在向用户询问缺失事实之前，构建一份合并的发现地图。

阶段规则：

• 当有子 Agent 可用时，使用并行子 Agent。
• 同时在各个发现领域启动它们。不要串行扫描。
• 如果子 Agent 不可用，改用聚焦的内联发现。
• 在阶段 3 之前合并结果。

步骤 3：运行发现并合并结果

前置条件：步骤 2 已完成，且任何 MODE 3 等待状态都已解决。

在以下发现领域收集结构化结果。 在你合并发现结果之前，不要开始阶段 3。

当子 Agent 可用时，需要同时覆盖的发现领域：

Agent A — 项目标识与结构

• 阅读 README.md、package.json / pyproject.toml / go.mod / Cargo.toml，了解项目名称和描述
• 列出目录树的前 2–3 层（排除 node_modules、dist、.git、__pycache__、.next、build）
• 识别 monorepo 工作区包及其角色
• 检查是否存在 AGENTS.md 或 CLAUDE.md（如找到则记录路径 — 用于阶段 4）
• 返回：项目名称、一句话用途、带注释的目录结构、Agent 文档路径（或 none）

Agent B — 技术栈与组件

• package.json（前端和后端依赖）、requirements.txt / pyproject.toml、go.mod、Cargo.toml、build.gradle
• 框架配置文件：next.config.*、vite.config.*、nuxt.config.*、angular.json、svelte.config.*
• 后端入口文件：server.ts、app.py、main.go、Application.java、config/application.rb
• docker-compose.yml — 服务、端口、环境变量、服务间依赖关系
• 返回：前端技术、后端技术、关键库、带端口的服务列表

Agent C — 基础设施、CI/CD 与部署

• IaC：terraform/、pulumi/、cdk/、serverless.yml、k8s/ 或 kubernetes/
• 容器配置：Dockerfile*（每个服务）、docker-compose.yml 部署配置
• CI/CD：.github/workflows/、.circleci/、Jenkinsfile、.gitlab-ci.yml、Procfile
• 云信号：*.aws.json、.aws/、gcp/、azure/、Dockerfile 中的基础镜像
• 监控：Datadog、Sentry、Prometheus、Grafana、CloudWatch 配置或依赖
• 返回：云服务商（推断或未知）、关键托管服务、CI/CD 平台、监控栈

Agent D — 数据、安全与外部 API

• 数据存储：prisma/schema.prisma、alembic/、migrations/、ORM 配置、.env.example 中的 DATABASE_URL、Redis/Kafka/RabbitMQ 依赖
• 认证 / 安全：认证中间件文件、JWT/OAuth/SAML/OIDC 依赖、密钥管理器（Vault、AWS Secrets Manager、Doppler）、HTTPS 配置、WAF 配置
• 外部集成：.env.example 键前缀（STRIPE_、SENDGRID_、TWILIO_、OPENAI_ 等）、依赖中的 SDK 包
• 返回：数据存储列表（名称、类型、用途）、认证机制、外部服务列表

Agent E — 测试与代码质量 （可与其他 Agent 并发运行）

• 测试配置：jest.config.*、vitest.config.*、pytest.ini、pyproject.toml [tool.pytest]、Playwright 配置、Cypress 配置
• 代码质量：.eslintrc*、biome.json、.prettierrc*、mypy.ini、ruff.toml、sonar-project.properties
• 本地设置：Makefile、CONTRIBUTING.md、docker-compose.yml 开发目标
• 返回：测试框架、代码质量工具、本地设置命令

所有 Agent 完成后，将它们的发现结果合并为一份统一的发现地图。将每个字段标记为 INFERRED [source] 或 UNKNOWN。标记为 UNKNOWN 的字段将成为阶段 3 的访谈问题。 在此合并地图存在之前，不要询问访谈问题。

完成条件：你已拥有一份合并的发现地图，并知道哪些字段仍需要访谈问题。

阶段 3：定向访谈

目的：仅解决发现阶段无法确定的缺口。

阶段规则：

• 只询问缺失的信息。不要一次性询问所有问题。

步骤 4：提出有针对性的访谈问题

前置条件：步骤 3 已完成。

将相关问题分组为自然的对话轮次。 只提问与剩余缺口匹配的轮次。

第 1 轮 — 组件方面的缺口 （如果服务或组件不明确）

• 目录结构中没有直观呈现的服务或组件？
• 扫描未发现的任何外部服务（第三方 SaaS、内部共享平台）？

第 2 轮 — 基础设施与部署 （仅当云服务商或部署模式为 UNKNOWN 时）

• 所使用的云服务商和关键托管服务？
• 服务如何部署？（虚拟机、容器、无服务器、PaaS？）
• 监控和日志技术栈？

第 3 轮 — 安全 （仅当认证机制为 UNKNOWN 时）

• 认证机制？（OAuth2、JWT、会话 cookie、API 密钥、SSO？）
• 授权模型？（RBAC、ACL、基于策略？）
• 任何值得注意的安全工具或审计实践？

第 4 轮 — 路线图与未来计划 （始终询问 — 无法推断）

• 任何值得记录的已规划架构变更或迁移？
• 影响架构的已知技术债务？

第 5 轮 — 身份与术语表 （如果在 README 或 package.json 中未找到）

• 主要联系人或团队名称？
• 任何需要定义的项目特定术语或缩写？

完成条件：每个剩余缺口都得到回答，或者未解决的缺口在预览中表示为 ``。

阶段 4：预览与写入

目的：在任何写入之前要求一个预览检查点，然后写入已批准的文件并总结未完成的 TODO。

阶段规则：

• 将预览视为必需的检查点，而不是客套。

步骤 5：展示预览并等待确认

前置条件：步骤 4 已完成，或步骤 3 已解决所有未知项。

1. 在写入之前，展示一份带标注的预览，包含完整的 ARCHITECTURE.md。
   • 将自动检测的值标记为 # inferred from [file]。
   • 将未解决的字段标记为 ``。
2. 询问：“这样看起来对吗？在我写入之前，有任何需要更正的章节吗？”
3. 等待明确确认。

在你为所选模式展示预览并收到继续进行的确认之前，不要写入或编辑 ARCHITECTURE.md、AGENTS.md 或 CLAUDE.md。 不要将沉默、部分反馈或暗示性批准视为确认。

完成条件：用户已审阅预览并明确确认你可以写入。

步骤 6：写入已批准的文件并总结未完成的 TODO

前置条件：步骤 5 已完成。

1. 在目标位置（根目录或包目录）写入 ARCHITECTURE.md。
   • 删除推断来源注释，因为它们仅供审阅，不应出现在最终文件中。
   • 对于 openspec/config.yml 引用： 仅当文件确实存在（如步骤 1.1 中所检查）时才包含它们。不要添加对不存在文件的引用。
2. 更新 Agent 行为文档（如果存在）。 如果 Agent A 找到了 AGENTS.md 或 CLAUDE.md，检查其中是否引用了 ARCHITECTURE.md。如果没有，则追加一个引用块，帮助 Agent 理解系统结构。如下所述，将此视为架构文档本身准备就绪后的次要后续编辑。
3. 打印一份简要总结，说明推断了什么、直接回答了什么问题，以及哪些 `` 章节仍需要人工输入。

完成条件：已批准的文件已写入，且剩余的 TODO 已总结。

交互原则

• 并行发现。 当可以使用子 Agent 时，为阶段 2 同时启动它们。在这种情况下，不要逐个扫描配置文件。
• 先扫描，后询问。 将访谈问题留给子 Agent 无法填补的真正空白。
• 默认重构。 当文件不符合模板时，建议重构，并使其成为容易的选择，而不是埋在最底部的选项 (c)。
• 单仓库意识。 根文档和包文档面向不同的受众。保持它们范围适当，并相互引用。
• 说明你发现了什么。 在刷新模式下，在询问任何内容之前，先告诉用户发生了哪些偏移。
• 写入前预览。 始终展示完整的生成文档，并在触碰文件系统之前获得确认。
• 先推断，再询问，询问后再省略。 带有明确 `` 标记的文档是可执行的。缺少章节的文档会悄无声息地产生误导。
• 保留人工编写的内容。 在刷新模式下，绝不静默删除内容。将其呈现出来并确认其是否仍然准确。
• 每次写入都注明日期。 每次写入时，将第 10 节中的 "Date of Last Update" 设置为今天的日期。

输出模板

加载 references/template.md 以获取完整的 11 节 ARCHITECTURE.md 骨架。

单仓库包文档： 在开头标题之后立即包含以下内容：

调整相对路径，使其指向实际的根 ARCHITECTURE.md。

更新 Agent 行为文档

ARCHITECTURE.md 是一份关于系统结构的技术文档。不要从它引用 Agent 行为文件。诸如 AGENTS.md 或 CLAUDE.md 之类的 Agent 行为文件应当引用 ARCHITECTURE.md，因为系统结构可能会影响 Agent 行为。

在你编写 ARCHITECTURE.md 之后，如果 Agent A 找到了 AGENTS.md 或 CLAUDE.md，请按顺序执行以下操作：

1. 读取 Agent 行为文件，并检查它是否已经提及 ARCHITECTURE.md。
2. 如果使用 CLAUDE.md，并且它只是指向 AGENTS.md，例如 @AGENTS.md，则改为更新 AGENTS.md。不要修改指针文件。将指针文件视为路由存根，而不是添加架构指导的地方。
3. 如果不存在 ARCHITECTURE.md 引用， 则添加或更新一个 ## Related Documentation 章节，其结构应遵循 accelint-onboard-agents 所用的相同结构（文件底部）：

## Related Documentation

- **ARCHITECTURE.md** — System architecture, deployment overview, component interactions
  _(Reference this when behavioral decisions depend on understanding system structure)_

4. 保持章节格式完全一致。 使用标题 ## Related Documentation。将每个条目格式化为：

- **<filename>** — description
  _(Condition or scenario by which this file is used)_

5. 如果已存在 ## Related Documentation 章节， 则将 ARCHITECTURE.md 条目添加到该列表中，而不是创建重复章节。保留现有的列表样式。将说明性使用注释保留在其自己的缩进行上。
6. 如果不存在真正的 Agent 行为文件， 不要作为此技能的一部分创建该文件。将写入限制在已批准的架构文档中。

完成条件：架构指导位于真正的 Agent 行为文件中，使用 ## Related Documentation 结构，并且不修改指针存根。