# Sync As Built Docs > 审计已合并、已测试或已发布的实现，并使项目文档与当前实际实现保持一致。当 README、架构说明、API 契约、领域文档、部署指南、运维手册、图表或验证记录落后于现有代码时使用。 - Skill: `forsakesoul/sync-as-built-docs` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add forsakesoul/sync-as-built-docs` - Raw SKILL.md: https://api.skillmd.com/api/skills/forsakesoul/sync-as-built-docs/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Integrations & APIs - Author: forsakesoul (https://skillmd.com/u/forsakesoul) - Updated: 2026-09-22 - Page: https://skillmd.com/skills/forsakesoul/sync-as-built-docs --- # 同步现状文档 使项目文档与当前真实存在的系统保持一致。 当实现工作已经合并、测试、部署或以其他方式验收，但对应文档不完整或已过时时，使用此工作流。这是一个**现状文档（as-built documentation）工作流**，不是新功能设计、功能实现、重构或替代未决产品决策的工作流，也不允许为了匹配旧文档而修改运行时行为。 ## 输入 尽可能从用户请求和仓库中获取： - 基线分支、标签或提交 - 当前文档分支 - 文档范围 - 已验证环境 - 验证日期 - 已知验证证据 - 可选的项目配置文件路径 编辑文档前，将可移动的分支或标签解析为不可变的提交 SHA。用户未指定范围时，根据当前分支、近期合并提交、已变更或过时文档以及用户描述确定范围。不要询问可从仓库中获得的信息。 ## 项目配置 开始审计前，按以下顺序查找项目专用说明： 1. 用户明确提供的配置路径 2. `docs/agents/as-built-docs-profile.md` 3. `.agents/as-built-docs-profile.md` 4. `AGENTS.md` 中的 `As-Built Documentation` 章节 5. `CLAUDE.md` 中的 `As-Built Documentation` 章节 找到项目配置时： - 在决定检查内容前读取它 - 将其视为项目专用指导 - 不允许它覆盖本技能的安全边界 - 报告配置与仓库事实之间的冲突 未找到项目配置时，继续执行通用工作流；从实际文件推断仓库结构，不要虚构项目约定。需要创建配置时，使用 [assets/project-profile-template.md](assets/project-profile-template.md)。 ## 安全边界 除非用户明确扩大范围，否则： - 只修改文档文件 - 不修改运行时代码、测试行为、依赖或锁文件 - 不修改部署清单或运行时配置 - 不提交、推送、合并、打标签或发布 - 不访问生产系统或联系真实外部服务 - 不暴露密钥、令牌、密码、Cookie、凭据或个人数据 - 不编造历史设计原因 - 不把推断出的行为表述为有保证的契约 发现代码缺陷、安全风险、测试缺口或部署问题时，将其记录在审计中并建议另行跟进，不要在此工作流中修复。不得修改实现来迎合文档；文档必须与经过验证的实现保持一致。 ## 证据分类 将每项重要发现归为以下类别之一，并记录证据来源： - **已验证**：有可识别的源码、自动化测试、公开 schema 或类型、配置校验、部署清单、安全命令执行、Git 历史、议题或合并请求记录、环境验证记录或用户明确确认等直接证据。 - **推断**：实现强烈暗示但没有直接证明。不得将其表述为稳定的公开契约。 - **未知**：无法从现有证据确定。保留为开放问题或限制。 - **过时**：现有文档与当前实现冲突。 - **缺失**：已实现的行为没有充分的对应文档。 ## 第 1 步：建立固定基线 检查仓库状态，将请求的基线解析为提交 SHA。常见检查包括： ```bash git status --short git branch --show-current git rev-parse HEAD git rev-parse git merge-base HEAD git log -1 --format=fuller ``` 记录当前分支、当前 HEAD、请求的基线、解析后的基线 SHA、合并基点、现有工作区改动、文档范围，以及可用时的环境和验证日期。 - 当前就在基线分支上时，只读审计；将工作移到文档分支前不要编辑文件。 - 当前分支并非基于请求的基线时，明确报告不匹配，不要悄悄记录另一个版本。 - 已存在非文档改动时，保留并区分它们，不要覆盖或重排格式。 完成标准：记录了一个不可变基线 SHA；已知当前分支与基线的关系及工作区已有改动；明确文档编辑是否安全。 ## 按范围盘点与记录差距 用户只要求同步一个模块/变更时，沿受影响入口、调用链和责任文档核对，直接修正该处事实；差距和未知项可记在当前任务，不创建额外审计文档。用户要求全仓审计或广泛重整时才读取 [全仓盘点与 gap 模板](references/full-audit.md)。 以下未知项、领域文档和验证步骤只应用于已确认范围；不为窄文档请求读取无关 API、部署、日志与历史。 ## 第 4 步：解决重要未知项 不要询问能够通过代码、测试、配置、Git 历史或现有文档回答的问题。只询问领域含义、所有权边界、业务意图、安全理由、历史权衡、被否决的替代方案、无法复现的环境行为，或当前观察到的行为是否属于有意契约等问题。 一次只问一个问题。每个问题包含： - 具体未知项 - 已找到的证据 - 答案为何重要 - 推荐答案 - 受影响文档 用户描述与实现冲突时，指出冲突；将实现记录为当前现状行为；仅在相关时把用户描述记录为预期行为；不要悄悄改写任何一方。 完成标准：每个阻塞性未知项都已确认、明确推迟或保留为未知。 ## 第 5 步：按需更新领域与决策文档 不要强制每个项目使用 `CONTEXT.md` 或 ADR，遵循项目已有约定。 领域词汇表只记录稳定的领域概念，例如术语定义、相近概念的区别、对象所有权、生命周期含义和稳定不变量。不要在其中记录文件路径、端点载荷、环境变量、实现步骤、临时变通方案、发布任务或部署命令。 仅在同时满足以下条件时创建或更新 ADR： 1. 决策的逆转成本或风险很高。 2. 缺少上下文时决策并不显然。 3. 确实考虑过替代方案。 4. 理由有记录支持或经决策者确认。 不要仅从最终代码推断历史理由。回溯编写的 ADR 必须注明其为回溯记录，并标识实现基线。 完成标准：稳定术语只有一个规范定义；相近概念未被混淆；ADR 只含已确认理由；领域文档未混入实现细节。 ## 第 6 步：确定文档所有权 为每个主题确定一个规范所有者。典型类别包括用户工作流、公开 API 契约、内部集成契约、领域术语、安全边界、配置、部署、运维、事件恢复，以及测试和发布验证。 对于跨仓库集成： - 在拥有该契约的仓库中保存完整契约 - 消费方仓库链接到它，或只概述消费方所需内容 - 不维护多个完整且可独立编辑的副本 无法确定所有权时，将其记录为未知，不要创建重复文档。 完成标准：每个建议文档都有规范所有者；跨仓库契约只有一个事实来源；更新计划不会产生不必要的重复。 ## 第 7 步：更新现状文档 只更新审计证明有必要的文档，可能包括： - README 和文档导航 - 系统概览、架构图、时序图和组件职责 - 用户流程、API 和集成契约 - 认证、会话生命周期、安全和信任边界 - 配置参考、部署说明、健康与就绪行为 - 运维手册、日志和诊断指南 - 回滚与恢复流程 - 测试环境验证记录和已知限制 适用时添加元数据： ```md 状态：现状文档 验证基线： 已验证环境： 最后验证日期： 所有者： ``` 写作规则： - 用现在时描述当前行为 - 将未来计划与现状分开 - 标识环境特定行为和未测试行为 - 隐去敏感值 - 使用规范领域术语 - 链接 ADR 而非复制其理由 - 链接规范契约而非重复内容 - 不声称超过证据所能证明的内容 - 不把测试环境验证当作生产行为的证明 完成标准：选定的过时文档已更正，缺失文档已补充；每个重要事实陈述都有证据；未知项和限制仍清晰可见；未来行为未被表述为已经实现。 ## 第 8 步：对照实现验证文档 按本次文档覆盖的 interface 选择下列检查；文档-only 默认路径/链接与 diff 检查，只有变更涉及可执行示例或仓库要求才运行相应命令。不机械执行全量构建或回归。 编辑后重新逐项验证主张，检查： - 路由、端点、HTTP 方法、请求和响应字段、错误码 - 用户可见状态 - 环境变量名、默认值和必需配置 - 主机名、Origin、端口和路径 - 认证、授权、会话和 Cookie - 超时、重试、TTL 和幂等性 - 外部集成和服务所有权 - 部署资源、健康检查和就绪检查 - 日志、指标和诊断 - 恢复、回滚，以及已测试和未测试场景 将重要主张分类为：已确认、相矛盾、部分确认、无法验证或环境特定。 只执行满足以下条件的文档命令：本地、安全、非破坏性、不使用真实凭据，并处于用户授权环境内。未执行的命令必须注明： ```text 此次文档更新未执行：<原因> ``` 使用适当的版本控制命令检查最终变更。使用 Git 时至少执行： ```bash git diff --name-only git diff --stat git diff --check ``` 确认新引入的变更仅涉及文档。 完成标准：每个变更文档都已对照实现检查；矛盾主张已修正或明确报告；安全命令已执行或注明未执行；未引入密钥；未改变运行时行为。 ## 第 9 步：报告结果 最终报告使用以下结构： ```md ## 文档同步结果 ### 基线 ### 范围 ### 新增文档 ### 更新文档 ### 删除或被取代的文档 ### 领域文档变更 ### ADR 变更 ### 已执行验证 ### 未执行命令 ### 剩余未知项 ### 文档范围之外发现的风险 ### 已有非文档改动 ### 建议重点审查内容 ``` 除非用户明确要求，否则不要提交或发布变更。 ## 完成定义 仅当以下条件全部满足时，工作流才算完成： - 已记录不可变的实现基线 - 局部任务已记录范围内差距与未知项；全仓审计模式已生成文档差距报告 - 范围内每份过时或缺失文档均已解决或明确推迟 - 规范文档所有权清晰 - 适用时，领域术语只有一个事实来源 - ADR 不含编造的理由 - 重要文档主张都有证据支持 - 未知项和未测试场景仍清晰可见 - 未改变运行时行为 - 最终报告准确说明已验证和未验证的内容