vibe-coding-cn/i18n/zh/skills/04-开发工具/ddd-doc-steward/SKILL.md

name: ddd-doc-steward

description: "文档驱动开发（DDD）文档管家：以仓库真实证据为准，盘点 ~/project 与 docs 目录，生成/更新 SSOT 文档（计划→补丁/全文→摘要→一致性检查）。触发：需要让文档与代码/配置/运行方式同步、补齐 guides/integrations/features/architecture/incidents/archive、无法推导时标注【待确认】并给验证路径。"

DDD 文档管家 Skill

让 ~/project/docs 成为单一可信来源（SSOT）：先盘点、后计划、再增量写文档，所有事实有证据来源，没有证据就【待确认】。

何时使用

• 需要为真实仓库建立/维护文档 SSOT，输出「盘点表 → 计划 → 文档补丁/全文 → 变更摘要 → 一致性检查」的固定交付物。
• 新增/改动功能、集成或事故复盘，需要同步更新 docs 下对应目录。
• 需要在 strict 模式下，避免任何臆测，所有关键事实必须给出代码/配置/命令的路径或说明验证方法。
• 只能获取部分信息时，仍需生成最小可落地模板并标注【待确认】。

不适用 / 边界

• 与工程无关的纯创作文案。
• 无法提供最小证据集（目录树、README/依赖/配置/路由位置）且不接受【待确认】输出时。
• 涉及密钥明文输出；文档中仅可写占位符与获取方式。
• 未提供 project_root/docs_root/output_mode 等输入时，先将自然语言归一到输入 JSON（参见快速参考）。

快速参考

1) 归一化输入（缺省值）

{
  "project_root": "~/project",
  "docs_root": "~/project/docs",
  "output_mode": "patch_diff",
  "truthfulness_mode": "strict",
  "change_type": "baseline",
  "scope_hint": null,
  "related_paths": [],
  "prefer_priority": ["guides","integrations","features","architecture","incidents","archive"],
  "enforce_docs_index": true,
  "use_git_diff": true,
  "max_doc_size_kb": 200,
  "style": "standard"
}

2) Phase A 扫描要点（证据链）

• tree -L 3 或目录枚举；rg 聚焦 README、依赖、配置、路由/API 定义。
• 记录证据路径清单（文件/命令），不写结论。

3) Phase B 先输出计划

• 《文档盘点表》：按六大目录标记「存在/缺失/疑似过期」，附证据路径。
• 《生成/更新计划》：新增/更新/待确认清单；理由=证据。

4) Phase C 生成文档（遵循 output_mode）

• patch_diff 推荐；无写权限时用 full_files。
• 每个文档必含 Purpose/Scope/Status/Evidence/Related/Changelog。
• 命名规范：ADR architecture/adr-YYYYMMDD-<kebab>.md；PRD/Spec/Integration/Guide/Incident/Archive 详见 references/api.md。

5) Phase D 收尾

• 变更摘要：每文件 3-8 条关键变化。
• 一致性检查：文档-代码验证点 + 未解的【待确认】与下一步。

6) 关键规则

• 真实性优先：无证据不写，写则附路径；敏感值用占位符。
• 没有就创建，有就增量更新，禁止大面积重写无关内容。
• 超过 max_doc_size_kb 拆分；缺少访问时生成模板并给证据采集命令。

规则 & 约束

• MUST：输出五段结构；严格遵守目录/命名规范；Changelog 每文必有；冲突以代码/配置为准。
• SHOULD：优先用 git diff/related_paths 聚焦；guides 与 integrations 先行；为每个【待确认】提供验证路径。
• NEVER：编造端口/环境变量/接口字段；输出密钥明文；跳过盘点直接写文档。

示例

示例 1：空仓库初始化

• 输入：change_type=baseline，docs 为空。
• 步骤：A 扫描→B 盘点表标记全部缺失→计划新增 docs/README.md、guides/getting-started.md 等→C 生成骨架补丁→D 摘要与检查。
• 验收：输出 patch diff，所有命令标【待确认】或给寻找路径。

示例 2：新增登录功能

• 输入：change_type=feature，scope_hint="auth 登录"，use_git_diff=true。
• 步骤：用 diff 找受影响路由；盘点 features/integrations；计划新增 PRD/Spec，更新 integrations/auth-api；标记 token 过期时间待确认。
• 验收：变更摘要指出新增文档与更新字段；检查清单含鉴权/错误码/验证 curl。

示例 3：无法读取仓库

• 输入：仅自然语言“帮我做 SSOT 文档”。
• 步骤：先归一化 JSON，声明“无法真实扫描”→生成六类文档模板，全量标【待确认】并列证据缺口与采集命令。
• 验收：输出 full_files；每条待确认可直接行动补证。

FAQ

• Q: 没有写权限怎么办？
  A: 将 output_mode 设为 patch_diff 或 full_files，给出可落盘内容。
• Q: 目录过大处理不过来？
  A: 按 prefer_priority 分批；声明本次范围与剩余批次计划。

维护

• 来源：i18n/zh/prompts/02-编程提示词/文档驱动开发/DDD 文档管家 Agent 工业级提示词.md；元技能 00-元技能/claude-skills/；自动化辅助工具 libs/external/Skill_Seekers-development.
• 最后更新：2025-12-20
• 已知限制：依赖用户提供真实证据；大体量仓库需分批；不输出敏感值。

质量门禁（出厂前自检）

1. name/description 符合触发条件、目录名一致。
2. 五段交付结构齐全；每段内容可直接给人/脚本消费。
3. 每个文档含 Purpose/Scope/Status/Evidence/Related/Changelog。
4. 所有事实有证据路径；无证据标【待确认】且给验证路径。
5. Quick Reference ≤20 条且可直接执行；示例 ≥3。
6. 长文本放 references/，references/index.md 可导航。
7. 安全：不输出密钥明文，敏感值使用占位符。