maintaining-core-documentation

维护核心文档

本技能提供了一套全面的框架，用于为任何软件项目或代码仓库创建和维护高质量、专业的技术文档。

目录

• 触发条件
• 强制初始化
• 核心原则
• 技术写作技能协同
• 文档维护指南
• 格式规则
• 文档审查流程

触发条件

本技能应在以下情况触发：

• 用户请求创建或审查文档。
• 用户新增 / 更改 / 删除功能，或对代码库进行重大更改。
• 用户对测试进行任何更改。
• 用户对部署进行任何更改。

强制初始化

在执行任何文档任务之前，你必须按照下方 技术写作技能协同 部分中的指引，检查是否存在 technical-writer 技能。

核心原则

1. 人设与风格：保持专业（"专家架构师"）、技术性强但友好的语气。在解释设计决策背后的"为什么"时，使用高层次的架构视角。
2. 跨文档同步：对核心属性（如项目 ID、URL 或文件路径）的更改必须立即传播到所有适用的文档文件中。
3. 阅读现有文档：始终阅读现有文档文件，以了解项目的当前状态和意图。
4. 技术栈：如果存在 conductor/tech-stack.md 文件，请阅读它以了解预期的技术栈。
5. 技术准确性：不要假设现有文档是准确或最新的。在更新文档之前，请验证代码库、配置设置（例如 config.py、Makefile、*.tfvars、pyproject.toml）、环境变量名称和命令标志。
6. 询问未知事项：
   • 通过提问帮助确定设计选择和技术选型。
   • 通过提问帮助确定任何缺少理由的设计决策的理由。
7. 技术写作协同：在执行文档维护时，如果（且仅如果）存在 technical-writer 技能，你必须使用它。如果未找到，请遵循下方的 技术写作技能协同 部分。

技术写作技能协同

technical-writer 技能可提高文档审查和创建的质量。

1. 确定 technical-writer 技能的可用性： 技能存在？ → 加载该技能并协作处理格式。 技能缺失？ → 遵循下方的"安装工作流"。

2. 安装工作流：

   • 使用 npx skills ls -g 检查可用性。
   • 向用户推荐该技能。
   • 如果获得批准，通过以下命令安装：npx skills add https://github.com/shubhamsaboo/awesome-llm-apps --skill technical-writer -g -y

文档维护指南

以下是本技能应维护的核心文档。你必须审查以下每个核心文档，并根据需要进行更新。

1. README.md（"门面"）

• 重点：快速上手和项目高层次目标。
• 模板：README.md.template
• 示例：README.md
• 关键部分：概述、关键链接（博客 / 在线演示）、项目结构（文件夹树）、设置（一次性 vs 每次会话）、实用命令（使用 Markdown 表格）。
• 触发条件包括但不限于：
  • 添加新的顶级目录。
  • 添加核心功能。
  • 添加 make 目标。
  • 更改本地开发设置工作流。

2. TODO.md（项目计划）

• 重点：整体项目路线图和任务跟踪。
• 模板：TODO.md.template
• 维护条件：仅当该文件已存在时才维护。你可以主动提出创建它，例如，当任务已完成和/或正在讨论未来任务时。
• 触发条件包括但不限于：
  • 完成一个步骤或更新项目时间线。
  • 如果被要求创建新的 TODO 条目。
  • 任务完成时主动提出将步骤标记为已关闭。

3. docs/DESIGN.md（视觉与 UX）

• 重点：视觉识别、UX 组件和设计令牌。可供 UI 设计集成使用，例如 Google Stitch。
• 模板：design.md.template
• 示例：docs/DESIGN.md
• 关键章节：视觉识别（排版、颜色）、视觉效果（例如玻璃拟态）、前端组件（布局、轮播、小组件等）、命令行 UX（如果存在）。
• 触发条件包括但不限于：
  • 实现 UI 框架时（例如 React、Vue、Angular、Svelte 等）。
  • 添加或更改任何 UI 组件时。
  • 修改视觉或样式时，例如修改 index.css 全局样式。

4. docs/architecture-and-walkthrough.md（“蓝图”）

• 重点：系统范围的架构逻辑和设计决策。评估任何变更是否引入了新的“设计决策”（ADR），应记录在 docs/architecture-and-walkthrough.md 中。
• 模板：architecture-and-walkthrough.md.template
• 示例：docs/architecture-and-walkthrough.md
• 关键章节：设计决策（以表格形式列出的 ADR 及理由）、解决方案架构、服务/模型关系、关键用户旅程 / 演练
• 触发条件包括但不限于：
  • 添加或更改设计决策。
  • 更改数据库 schema。
  • 修改 Agent 编排逻辑。
  • 添加或更改编码框架。
  • 更改或引入新的基础设施托管服务（例如在 GCP 上）。
  • 添加安全组件或功能。
  • 添加一个层（例如前端、API、后端、持久化等）。

5. docs/testing.md（质量保证）

• 重点：我们如何验证应用程序的正确性。
• 模板：testing.md.template
• 示例：docs/testing.md
• 关键章节：范围（例如 Python、前端、Agent）、工具（pytest、ruff 等）、CI/CD 环境的具体情况（本地 vs CI=true）、单元/集成/E2E 测试描述、手动验证步骤（例如用于速率限制的 curl 脚本）。
• 触发条件包括但不限于：
  • 添加 / 更改 / 移除测试。
  • 更改 mock 策略。
  • 引入新的质量门禁工具。

6. deployment/README.md（基础设施）

• 重点：预配和管理基础设施环境。
• 模板：deployment-README.md.template
• 示例：deployment/README.md
• 关键部分：部署方式（例如脚本、Terraform，或两者兼用）、Terraform 结构、先决条件、变量传递（env.tfvars -> substitutions -> runtime）、机密管理、CI/CD 流水线。
• 维护条件：所有项目都应有某种形式的部署文档。如果不存在，应主动提出创建。每当更改部署流程时，都要更新此文档。
• 触发条件包括但不限于：
  • 添加新的 Terraform 资源。
  • 启用 API。
  • 更改部署脚本。
  • 添加新的服务。
  • 更改或绑定 IAM 角色。
  • 更新安装先决条件。
  • 更新 CI/CD 流水线逻辑、更新 GitHub Actions、更新 Cloud Build 等。

7. conductor/ 文档（实现细节）

• 重点：产品逻辑、产品品牌、指南和技术栈详情。这些文档由 Gemini Conductor Extension 自动管理，但如果在 Conductor 之外进行了更改，则应更新这些文档以反映相应更改。
• 范围内的文件：product.md、product-guidelines.md、tech-stack.md。
• 严格排除项：绝不要修改 conductor/ 目录中的任何其他文件，包括但不限于：workflow.md、tracks.md、setup_state.json，以及 code_styleguides/ 或 archive/ 目录中的任何文件。
• 维护条件：仅当这些文档已存在于代码库中时，才维护它们。
• 触发条件包括但不限于：
  • 技术栈发生重大变化。
  • 产品品牌发生变化。
  • 重新定义产品逻辑。
  • 请求审核产品一致性或技术栈合规性。

格式规则

• 标题：每个 Markdown 标题后必须留一个空行（例如，# Header\n\nContent）。这样可确保在所有 Markdown 查看器中一致呈现。
• 表格：配置、模型字段和设计决策始终使用表格，以提升可读性。
• 代码块：所有代码都必须用带有适当语言标识符的围栏代码块括起来。
• 图表（绝不使用 Mermaid 或 ASCII）：
  • 在任何文档文件（README.md、ARCHITECTURE.md、docs/*.md）中，绝不要创建、插入或输出基于文本的 mermaid 代码块（```mermaid）或 ASCII/Unicode 框线图。
  • 需要可视化图表（架构、组件关系、序列、部署流程）时，始终使用图像生成工具生成 PNG 图片，将其保存到代码库中（例如 media/ 或 docs/images/），并通过相对 Markdown 链接嵌入（![Diagram Caption](media/diagram.png)）。

文档审核流程

复制此检查清单，并在更新文档时跟踪进度：

Documentation Update Progress:

- [ ] Step 1: Identify which of the core documents are impacted by code changes.
- [ ] Step 2: Verify that NO out-of-scope files (e.g. `workflow.md`, `code_styleguides/`) are included in the review.
- [ ] Step 3: Assess if the change introduces a new "Design Decision" that should be recorded in `docs/architecture-and-walkthrough.md`.
- [ ] Step 4: For all identified core documents, draft updates as per Document Maintenance Guide, and using the appropriate templates in the `./references` directory and using the samples in `./references/samples/`.
- [ ] Step 5: **Structural & Diagram Validation**: Perform a manual or automated check (e.g. using `grep`) to ensure every markdown header is followed by a blank line and that NO `mermaid` blocks or ASCII diagrams were introduced.
- [ ] Step 6: Review against the formatting rules in the [Formatting Rules](#formatting-rules) section.
- [ ] Step 7: Check that the identified core documents have been updated. If any changes have been missed or performed incorrectly, go back to Step 2 and repeat.
- [ ] Step 8: Check that the change aligns to the formatting rules. If not, fix them and go back to Step 6.
- [ ] Step 9: Only finalize and save when all requirements are met.
- [ ] Step 10: Summarise with a table of which documents were updated and what changes were made. Also include which documents (if any) were not updated and why.

汇总表格式

在文档审核流程的最终汇总步骤中，使用以下表格结构汇总工作：

文档	状态	更改摘要 / 理由
README.md	[已更新/无更改]	[简要说明更改内容，或说明无需更新的原因]
TODO.md	[已更新/无更改]	[例如：将步骤 4 标记为已完成]
docs/DESIGN.md	[已更新/无更改]	[例如：在 frontmatter 中添加新的颜色令牌]
...	...	...