渐进式项目文档
让文档随着项目的真实需要生长，也能在重复或失效时收缩。目标是让使用者、开发者和 AI 找得到、读得懂、可以据此正确行动的信息，而不是达到某个文件数量。
选择本次工作模式
- 首次梳理：检查项目与现有文档，补最有价值的缺口；空项目也可能只需要 README。
- 增量维护：从本次功能、修复或配置 diff 出发，仅更新受影响的说明与索引。文档已生成过不是重建理由。
- 重组治理：针对重复、矛盾、难以查找或变化频率不同的内容，保留、合并、拆分、改名或归档。
用户只要建议时，交付有依据的方案；用户要求生成或维护时，完成可验证的文档修改。普通代码任务中使用此技能只补相关文档，不将任务扩展为全仓库文档整治。
先确认真实项目
先读取适用项目指令和已有导航。若有 Git，检查分支、HEAD、工作区与相关 diff；没有 Git 也可以从目录、源文件和已有材料工作。保留未提交改动，不自动初始化 Git、发布或推送。
按目标读取最少必要证据：
- README、已有 docs/wiki/站点导航、贡献指南、Agent 指令；不要只按文件名判断内容。
- 实际入口、模块边界、数据归属、接口类型、配置与构建命令。
- 使用者、开发者或运维真正需要完成的任务，以及用户明确给出的项目方向。
- 当前任务来源，例如 Issues、看板、TODO；已有单一来源时优先链接，不再维护第二套进度。
通用搜索避开凭据、会话、客户数据、构建输出和无关目录。不要为了写说明读取密钥值或导出完整运行数据。交接和历史说明是待核实证据，不能替代当前代码。
决定最小文档变更
对于每个候选主题，回答：谁会读？要做什么决定或操作？现有哪一处已经回答？什么新变化使它需要独立维护？ 回答不清楚时暂缓独立文件。
优先顺序是：复用已有内容 → 补一个章节 → 必要时新增文档 → 有充分理由才拆分/改名。目录大小、项目年龄、代码行数不能单独决定文档数量。采用项目现有语言、命名、目录和发布方式；无需强制 docs/ 或某组固定文件名。
大规模生成前简短说明修改、合并和暂缓项及依据；这不是额外审批步骤。可在回复中保留决策，不默认生成“文档规划报告”。主题边界不清楚或首次设计体系时读取 主题选择指南。
新增或拆分的有效信号：
- 有实际读者反复需要的操作步骤，原入口已不能清楚承载。
- 跨模块边界、数据流或外部契约成为开发决策依据。
- 同一视觉或行为规则需要多个界面一致复用。
- 某部分有独立读者、变化节奏或负责人，嵌在原文中已难查找。
- 同一事实在多处重复造成冲突，需要一个权威位置和引用。
没有这些信号时，可以只改几句话，甚至明确说明当前无需文档变更。
生成与更新
围绕读者任务组织内容，给出能执行的步骤、约束和必要例子。不要堆砌源码目录清单、复制完整类型定义或生成空章节占位。能从代码生成的完整 API 优先采用已有生成机制，人工文档解释语义、边界和失败处理。
| 信息性质 | 写法 |
|---|---|
| 当前实现 | 给出源码或配置依据；必要时限定平台、版本或范围 |
| 项目约束 | 明确这是必须遵守的规则，不暗示已全部审计通过 |
| 待实现方案 | 标明计划或待办，列验收条件，不写成当前可用能力 |
| 验证结果 | 只记录执行过的检查与环境；编译通过不等于真机验证 |
| 未确认事实 | 明确不确定点和核验方式，不用推断填充保证 |
稳定事实不必每页写版本号；易变契约或验证记录按需标注基线。优先使用仓库相对链接，避免把开发者绝对路径、私人主机名和会话标识写进通用文档。
每个主题只保留一个主要维护位置。README 负责入口和概览，Agent 指令负责必要约束和导航，其他文档负责细节，但按项目已有结构调整。不要因拆分移除 Agent 必须直接看到的关键保护规则。
已有多语言文档同步受影响的语义与链接；不无依据新增整套翻译。记录缺陷到项目任务渠道时遵守写入授权，不未经要求创建外部 Issue。文档工作不自动授权修复业务代码。
随开发持续维护
相关变更收尾时检查“行为是否改变”，而非“哪些 Markdown 恰好被编辑”。
| 变更 | 通常需要检查的内容 |
|---|---|
| 使用步骤、默认值、故障恢复 | 快速开始、用户指南、示例与限制 |
| 模块、进程、状态、数据位置 | 架构、数据流和已有图表 |
| API、IPC、事件、CLI、错误码 | 参数/返回值、作用域、生命周期、兼容与错误处理 |
| 主题、布局、交互或无障碍 | 设计规则与视觉回归项 |
| 工具链、测试、构建、发布 | 开发命令、CI/发布说明和下载入口 |
| 实现任务或完成验证 | 既有任务状态及验收证据 |
纯内部重构且外部行为、架构边界与开发方式均未变化时，可能无需更新文档。不要为每个 commit 追加一次日志。
重复执行时以当前状态为准：已满足的信息不重复生成，导航不重复追加，已完成任务不反复创建。重组前查找链接和调用方，更新引用；已发布链接按需保留迁移入口，历史决策仍有价值时归档。未经用户授权或项目明确规则允许，不删除用户文档。
“持续维护”是在技能被调用或被开发流程选用时执行，不代表自动后台监控。不擅自创建计划任务、Git hook 或 CI。用户要求接入项目流程时，再把精简的文档影响检查加入现有 Agent/贡献规范。
验证与交付
- 核对修改文件的相对链接、命名、导航和旧路径引用；报告检查范围。
- 与真实签名对照参数、序列化字段、事件和错误码；区分不同 ID 及权限/租户/实例绑定。
- 核对示例的工作目录与环境前提。不要为验证文档运行删除、迁移、安装或发布等有副作用的命令。
- 有文档构建、链接检查或 lint 时按范围运行。纯 Markdown 不默认重建整个应用；行为代码也变更时另做对应检查。
- 有 Git 时检查 diff 和空白错误，确认无无关改动、秘密或缓存；新文件也纳入检查。
交付说明新增/完善/合并了什么、为何适合当前阶段、验证方式与真实未完成项。给出入口链接和提交/推送状态。用户已授权发布时按授权执行；技能本身不授予未来所有项目公开上传权限。
