Johan409IA/skills

项目文档

帮助创建并保持软件项目完整文档集的最新状态，遵循固定结构以及 AGENTS.md 和 MEMORY.md 之间的固定关系。当用户希望从头生成文档、在更改后刷新文档或保持文件间一致性时使用。

目标结构

此技能管理的每个项目都应逐渐趋向于此布局：

mi-proyecto/
├── README.md              # 项目是什么，如何启动
├── AGENTS.md               # 代理的规则和指令
├── MEMORY.md                # 当前决策与已放弃的方案
├── CHANGELOG.md              # 版本间更改内容
├── DESIGN.md                 # 视觉设计系统（仅当存在 UI 时）
└── docs/
    ├── architecture.md
    ├── plans/                # 代理计划，每个文件一个
    └── (OpenAPI + Scalar 从 API 的 /docs 路径提供)

如果项目已有部分文件，请先读取它们并就地更新——不要盲目覆盖。如果缺少某个文件，请根据相应的模板创建。

工作流程

1. 调查现有内容。 列出项目根目录和 docs/ 目录以查看哪些文件已经存在。完整读取任何现有的 AGENTS.md/MEMORY.md/CHANGELOG.md/README.md/docs/architecture.md——它们设计得很简短。
2. 确定范围。 如果用户提到了特定文件（“更新 CHANGELOG”），则集中处理该文件，但仍需检查该更改是否应传导到 MEMORY.md 或 AGENTS.md（参见下面的传播规则）。如果用户说了类似“记录我的项目”或“更新文档”这样的通用话语，则处理上述结构中的每个文件。
3. 收集事实 从代码库本身（包清单、入口点、脚本、路由、最近的提交）收集所需信息，而不是猜测。不要编造命令、栈细节或端点——通过阅读代码或配置文件来验证它们。
4. 编写或更新每个文件 使用相应的参考模板。严格遵守 AGENTS.md（约30-40行）和 MEMORY.md（约50行）的长度限制——这些是承载约束，而非建议，因为代理在每个会话中都会重新读取这些文件，臃肿的版本会失去作用。
5. 报告结果 说明哪些文件已创建或更新，并标记您无法验证的任何内容（例如“未找到测试命令，请确认”）。

各文档

README.md

回答“这是什么以及如何运行”给人类查看。参见 references/readme-template.md。直接从项目实际脚本（package.json、Makefile、pyproject.toml 等）中提取运行/安装/测试命令——切勿猜测命令名称。

AGENTS.md

在此仓库中工作的编码代理的指令。请参考 references/agents-template.md 了解确切的章节和顺序。硬限制：总共约30-40行。如果它已经更长，您在更新时的工作既包括添加也要注意修剪——将任何看起来像临时决策或进行中说明的内容移入 MEMORY.md，并只在此处保留持久规则。

MEMORY.md

会话间记忆：当前真实状态，关键决策的原因，尝试过但被拒绝的方案，下一步计划。参见 references/memory-template.md。硬限制：约50行。更新时，主动进行修剪——删除或压缩不再重要的条目，而不是让文件无限增长。

AGENTS.md 和 MEMORY.md 的关系（这是核心约定——请确保正确）：

• AGENTS.md 必须包含一个简短的“记忆”部分，告诉代理在任务开始时读取 MEMORY.md，并在任务结束时更新它。使用以下确切的措辞作为基础，仅当项目已使用不同措辞时才进行调整：

  ## 记忆
  - 开始时，读取 `MEMORY.md` 以了解项目状态和已做的决定。
  - 完成任务后，更新它：当前状态、重要决策（及其原因）和要避免的错误。
  - 保持简洁（最多约50行）：总结或删除不再有价值的内容。
  - 如果某件事成为永久规则，建议将其移动到 `AGENTS.md`，而不是留在记忆中。
  - 切勿存储敏感数据（密钥、令牌、个人数据）。
  

• AGENTS.md 的“限制”部分必须包含 ✅ 始终：完成任务后更新 MEMORY.md。
• 传播规则：MEMORY.md 包含目前真实的事情——当前状态、带有推理依据的决策、经验教训、下一步计划。AGENTS.md 包含始终真实的事情——永久规则、约定、技术栈、限制。当 MEMORY.md 中的某个内容不再是单一决策而变成了持续规则（例如“我们决定永远不使用 X”变成了“永远不要使用 X”），将其提升到 AGENTS.md 并从 MEMORY.md 中移除。当更新任一文件时，始终检查是否应进行此提升。
• 切勿将秘密、令牌或个人数据写入任一文件。

CHANGELOG.md

回答“版本之间发生了哪些变化。”遵循 Keep a Changelog 约定（在每个版本下使用 新增/变更/修复/移除，最新的在上面，并在顶部为进行中的工作保留一个 未发布 部分）。参见 references/changelog-template.md。更新时，随着工作的进行在 未发布 下添加条目，只有用户指示发布时才创建一个新的带日期版本部分。

DESIGN.md

回答“它看起来像什么以及 UI 应该如何构建”——视觉设计系统，由生成 UI 的代理读取。它位于项目根目录（不在 docs/ 中），与 AGENTS.md 相邻。它遵循开放的 Google Stitch DESIGN.md 格式（规范：github.com/google-labs-code/design.md，当前为 alpha）。参见 references/design-template.md 了解模板和每个块的说明。

• 仅适用于具有用户界面的项目（Web、移动、桌面）。如果项目是纯 API/CLI/库且没有 UI，请不要创建它，并在报告中说明。
• 两层结构：带有机器可读令牌（colors、typography、rounded、spacing、components）的 YAML 前置元数据——这些是规范值——以及解释原因的 markdown 主体。令牌说明什么；散文说明何时以及为什么，并通过名称引用令牌而不是重复十六进制代码。
• 章节顺序固定：概述 → 颜色 → 排版 → 布局 → 阴影与深度 → 形状 → 组件 → 应做与不应做。将这些标题保持原样用英文书写（工具通过名称匹配它们；别名 Brand & Style、Layout & Spacing 和 Elevation 也可接受），并用项目的语言编写散文。章节可以省略但不能重新排序，重复的标题是错误。允许额外的章节（例如图标与图像、动效、可访问性）——始终将它们置于“应做与不应做”之后。
• 从代码中获取值，切勿编造：Tailwind 配置、CSS 变量（:root、globals.css）、UI 库主题文件、已加载的字体、Figma/DTCG 令牌导出。如果项目有 UI 但尚未定义视觉标识，请提出值并在报告中标记为“提案，请确认”。
• 如果 DESIGN.md 已存在，请读取它并就地更新——切勿静默覆盖。当颜色、字体或间距发生变化时，保持令牌与代码同步。
• 无严格的行数限制（它是一个参考文档，如 docs/architecture.md），但保持每个章节聚焦：3-6个要点或一个简短的段落。
• 验证：如果 Node 可用，运行 npx @google/design.md lint DESIGN.md 并修复错误（broken-ref）和合理的警告（missing-primary、contrast-ratio、section-order）；否则告知用户该命令。
• 如果 AGENTS.md 存在且未提及 DESIGN.md，向用户建议（不要自行应用）添加一行指向，以便 UI 代理在生成 UI 前先读取它——注意 AGENTS.md 约30-40行的限制。

docs/architecture.md

回答“这是如何构建的”——组件、数据流、关键设计决策及其原因、显著约束。参见 references/architecture-template.md。这是唯一可以比其他文档更长的文档，因为它是参考文档，而不是每个会话都会重新读取的内容——但仍优先使用图表和简短章节而非长篇散文。在有助于展示主要组件/数据流视图时，使用 mermaid 图表。

docs/plans/

当代理为重要任务（多步骤实施计划、迁移计划、重构计划）生成计划时，将其作为单独文件保存在此处，而不是只留在聊天中。如果目录不存在，请创建它。命名文件为 YYYY-MM-DD-short-slug.md（例如 2026-10-03-add-payment-webhook.md），以便按时间顺序排序。每个计划文件应自包含：目标、方法、步骤、未决问题。完成计划后不要删除旧计划——它们是历史记录；如果项目想要一个“已完成”标记，请在文件顶部添加一行状态说明，而不是删除文件。

API 文档——OpenAPI + Scalar

这些不是静态的 markdown 文件——它们是从 API 实时提供的，通常通过 Scalar 的 API 参考渲染器在 /docs 或 /reference 路由上读取 OpenAPI 规范。当被要求设置或更新 API 文档时：

1. 检查项目是否已生成 OpenAPI 规范（框架装饰器/注解、openapi.yaml/openapi.json 文件或依赖中已有的规范生成库）。
2. 如果规范存在但尚未通过 Scalar 提供服务，请为项目的框架连接 Scalar 中间件/处理程序（Scalar 有大多数常见后端框架的官方集成——检查当前包名称/API，而不是假设，因为这个生态变化很快）并将其挂载到 /docs。
3. 如果规范尚不存在，则从现有路由/处理程序生成一个（大多数框架都有一个库可以根据路由定义/类型推导出 OpenAPI——优先使用这种方法，而不是手写 YAML），然后再连接 Scalar。
4. 如果框架可以从代码推导出 OpenAPI，绝不要手动维护一个巨大的静态 OpenAPI YAML——这会立即不同步。优先使用代码优先生成。
5. 一旦设置好，在 README.md 中注明 /docs URL，以便人类知道在哪里找到它。

完成前检查清单

• AGENTS.md 不超过约40行，并包含指向 MEMORY.md 的“记忆”部分
• MEMORY.md 不超过约50行，且没有永久内容搁置在那里而应属于 AGENTS.md
• README.md 中的命令已针对实际项目配置进行验证，而非假定
• CHANGELOG.md 遵循 Keep a Changelog 格式，带有 未发布 部分
• DESIGN.md（仅当项目有 UI 时）位于项目根目录，其令牌与实际代码匹配，章节遵循规范顺序，且 npx @google/design.md lint DESIGN.md 报告无错误
• docs/architecture.md 反映当前结构，而非过时的结构
• 新的代理计划已保存到 docs/plans/ 中，并带有带日期的文件名
• 未将敏感内容（密钥、令牌、个人数据）写入任何文档