docs

文档

在 docs/ 中创建并维护项目文档，采用一致、轻量的结构。

输出

维护以下内容：

1. docs/SUMMARY.md — 文档入口，包含 Agent Context Guide（始终重新生成）
2. docs/architecture/ — 系统设计、基础设施、组件交互、数据流和功能流程。重点关注_系统如何运作_，而不是文件／代码结构。
3. docs/codebase/ — 文件组织、目录结构、入口点、关键模块及其职责。重点关注_代码中的内容位于何处_。
4. docs/code-standard/ — 编码约定、命名规则、风格指南、环境设置、自定义规则和团队遵循的模式。重点关注_如何编写符合现有代码库的代码_、最佳实践和团队约定，这对保持一致性非常重要。
5. docs/project-pdr/ — 产品目标、用例、业务规则、约束和决策依据。建议包含较多用例／需求文件。

同时确保 README.md 与当前文档链接和项目概述保持一致。

工作流

第 1 步：上下文扫描

扫描项目，了解需要记录哪些内容：

1. 阅读现有文档（如有）（docs/SUMMARY.md 和主题文件夹）
2. 阅读 README.md 和关键配置文件（package.json、tsconfig.json、Cargo.toml 等）
3. 扫描源代码目录，了解项目结构、入口点和主要组件
4. 更新现有文档时，检查 git log --oneline -20 了解近期变更

重点关注事实：功能、架构、技术栈、目录结构和工作流。不要臆造需求，也不要假设代码中没有体现的业务逻辑。

第 2 步：推断行为

• 根据当前 docs/ 的状态，推断仓库需要初次编写文档还是增量更新。
• 如果 docs/ 不存在或明显不完整，则执行初始化行为。
• 如果 docs/ 已存在且结构标准，则执行更新行为。
• 适当时简要说明推断出的行为。

第 3 步：编写文档

在缺少文档或文档不完整时初始化

1. 创建 docs/ 和 4 个主题文件夹：architecture/、codebase/、code-standard/、project-pdr/
2. 对每个主题文件夹： a. 扫描代码库，查找相关信息 b. 根据代码库扫描结果生成内容 c. 根据代码库中发现的内容创建主题专属文件。按内容命名文件（例如 components.md、conventions.md）。不要使用通用名称（overview.md、index.md、main.md）。当内容涉及 2 个或更多明显不同的子主题时，将其拆分为多个文件。每个文件夹至少创建 1 个文件。
3. 按照“内容要求”中指定的格式创建 docs/SUMMARY.md，并包含 Agent Context Guide
4. 在 README.md 中添加指向 docs/SUMMARY.md 的链接

在每个文件中填写具体且针对项目的内容。避免使用占位符和通用模板。

在已有文档时更新

1. 检测变更：将当前代码与现有文档进行比较。使用 git log --oneline 和源文件扫描来识别新增、修改或移除的组件。
2. 保留有用的现有内容和章节结构。
3. 在原处更新过时或不准确的章节——不要从头重写。
4. 添加新发现的功能、组件或约定。
5. 删除明显过时的说明。
6. 根据内容变更，按需添加、修改或移除详细文档文件。
7. 重新生成 docs/SUMMARY.md 以匹配当前文件——只列出磁盘上实际存在的文件，并保留 Agent Context Guide。
8. 如果文档链接发生变化，则更新 README.md。

重要：目标是进行增量、精准的更新，而不是全面重写。

第 4 步：同步 README

确保 README.md 包含：

• 简短的项目概述
• 快速开始指南（如果项目中有）
• 指向 docs/SUMMARY.md 的文档链接

步骤 5：验证质量

完成前，请确认：

• docs/SUMMARY.md 存在，并列出磁盘上实际存在的每个详细文档文件（不得有虚构条目）
• 每个主题文件夹至少有 1 个主题专属文件
• 主题文件夹中没有通用文件名（overview.md、index.md、main.md）
• README.md 中的链接指向 docs/SUMMARY.md
• SUMMARY.md 简洁，包含 Agent Context Guide，并为所有部分提供文件表格
• 各文件中的术语保持一致
• 文档与代码之间没有矛盾
• 路径和组件名称准确
• 内容简洁、具体且可执行

内容要求

SUMMARY.md 格式

包含项目概述、简洁的 Agent Context Guide，以及每个文档部分的文件表格。

严格遵循 references/summary-template.md 中的模板。

Agent Context Guide 必须仅限于项目上下文加载：

• 如果 docs/SUMMARY.md 存在，先阅读它
• 仅加载与任务相关的详细文档
• 优先参阅 Code Standard 文档，了解实现规范
• 如果文档与代码或用户意图冲突，先根据现有输入/问题进行判断，再进行大范围更改

不要使用该指南重复介绍通用工程原则、Git 规则或详细的问题工具使用流程。

主题文件规则

• 每个文件只聚焦于其文件夹中的 1 个特定子主题
• 根据内容使用简短文件名：components.md、conventions.md、product-goals.md
• 不要使用通用名称：overview.md、index.md、main.md、general.md
• 保持文件内容聚焦且简洁，不强制规定行数

边缘情况

• 极简/空项目：如果代码库中的代码很少，主题文件应保持简短且基于事实。不要为了达到随意设定的篇幅目标而填充内容。如果确实暂无内容可记录，请将相应部分标记为“待定——随着项目发展再补充文档”。即使每个文件夹只有 1 个文件，也应根据内容命名。
• docs/ 中的自定义文件：保留 4 个标准主题文件夹之外的所有用户创建文件（例如 docs/API.md、docs/deployment.md）。在 SUMMARY.md 的“其他”部分列出这些文件。不要移动或重命名它们。
• Monorepo：如果项目包含多个包/应用，应在 architecture/components.md 中记录整体结构，并说明每个包的用途。无需为每个包单独创建完整的文档集；文档规模应与项目相称。

规则

• 文档内容必须基于事实；不要臆造要求。
• 优先进行简洁更新，避免冗长叙述。
• 文档应与当前实现保持一致。
• 不确定时，明确标注假设并请求确认。
• 如果无法可靠推断信息（例如业务目标、模块归属不明确、规范冲突、架构决策不清晰），请提出有针对性的问题。