文档组织准则

根据任务需要组织和维护项目知识，减少重复维护和无关上下文。用户要求、仓库中的明确指令和项目约定优先于本准则。

适用范围

• 创建、修改、整理、审查或查阅软件项目文档时，按相关职责应用本准则。
• 代码开发任务中，检查变更是否需要同步相关文档，并按复杂度和交接需要维护工作上下文。
• 分析、审查和方案讨论以结论与建议为交付；文档修改依据用户请求和已授权的开发任务执行。
• 普通代码修改只检查直接相关的文档，不因此扫描全部文档或创建计划。

文档类型

按用途和生命周期区分以下三类文档，后续统一使用「常驻文档」「工作文档」和「归档文档」称呼。

文档类型由内容职责和工作状态决定，不由文件名或所在目录决定；推荐位置不构成创建或迁移要求。

按需组织文档

先了解当前任务涉及的文档入口和项目约定，再决定读取、更新或新增哪些文档。

• 所有文档和目录均按需创建；不得仅为满足推荐结构而创建空文档或空目录。
• 本准则中的文件名和目录名仅作推荐。优先沿用已有合理结构，不要求重命名或迁移。
• 可以根据实际需要自行创建 API 参考、部署指南、运维手册或模块文档等其它文档，推荐清单不是封闭集合。
• 优先更新已有的权威文档；只有内容需要独立维护、职责需要拆分或可发现性确实需要改善时，才新增文档或入口。
• 用户要求整理，或现有结构确实妨碍当前任务时，再提出迁移方案；迁移应纳入已授权的改动范围。

需要选择文档位置或澄清职责边界时，查阅 文档职责参考。

保持当前知识可靠

• 每份文档应有明确的读者、用途和内容范围。职责容易混淆时，简要说明负责和不负责的内容，不强制固定字段或模板。
• 同一份当前有效的项目知识应有一个明确的权威来源。其它位置优先使用链接、引用或必要的简短摘要，避免复制完整规则。
• 区分合理的简短说明与需要多处同步的重复维护；已有专题文档时，入口文档保留摘要和引用。
• 代码、架构、配置、命令或用户可见行为变化时，检查相关常驻文档是否需要更新，不要求每次代码变更都产生文档修改。
• 用代码、配置和验证结果确认实际行为，用用户要求及明确契约判断预期行为。代码与文档冲突时，不能仅因代码如此实现就把它写成规范。
• 无法确定代码存在缺陷还是文档已经过时时，报告具体分歧和待确认事项，不猜测或自动改写文档来消除表面冲突。

按任务选择上下文

• 按任务需要选择相关常驻文档和工作文档，不无差别加载全部文档。
• 常规开发、Bug 修复、重构和方案评估不主动检索或加载归档文档。搜索项目内容时，排除已识别的归档位置。
• 用户要求追溯历史，或任务确实需要调查历史演进、问题或决策时，才查阅相关归档文档，不扩大为读取全部历史记录。
• 常驻文档指向归档文档的链接不意味着需要自动跟随读取，也不使归档文档成为当前依据。
• 归档文档及其引用不保证准确或仍然有效。涉及当前状态或技术事实时，通过代码、当前文档、验证结果或其它可靠来源重新核实。

维护进行中的工作

复杂、长期或需要跨会话、跨开发者交接的任务，可以自行创建和更新工作文档。

• 根据需要记录目标、范围、实现思路、进度、关键决策、未解决问题、验证情况和下一步，不要求固定章节。
• 有关联的常驻文档时，记录相应入口，便于任务结束时同步长期知识。
• 优先记录难以从当前代码恢复、又可能影响后续判断的设计意图、决策依据和工作上下文，不复述 Git 已能表达的代码变化。
• 简单、短期且无需额外交接上下文的任务，直接完成开发与验证，不创建工作文档。

结束任务与归档

任务结束时，按实际需要处理相关工作文档，不强制所有任务经过完整归档流程。

1. 识别最终架构、开发约束、使用方式等需要长期维护的知识，整理到合适的常驻文档，避免只保存在历史计划中。
2. 如需保留过程或决策依据，记录任务结束日期、真实的最终状态，以及知识迁移到的文档或章节。
3. 将有历史价值的工作文档移入归档位置，并同步受影响的入口和链接。
4. 没有保留价值的临时文档，仅在由本次任务自行生成时可自行删除；已有工作记录默认保留，不顺手清理归档文档或无关文件。

被终止、取消或替代的任务应如实记录状态，不描述为成功完成。重要历史记录可以直接创建在归档位置，不必先创建进行中的工作文档。

不为符合当前状态而重写归档文档；允许保留后来被证实错误的判断和失败方案。

完成前检查

• 文档职责和位置符合项目约定，没有仅为凑结构而新增文件。
• 当前知识已放入适合长期维护的位置，没有产生相互冲突的重复来源。
• 实际行为与预期行为已区分，无法确认的技术陈述或冲突已明确指出。
• 修改后的 Markdown、相对链接、文件路径和示例有效；移动文档后，相对引用与入口已同步。
• 工作文档的进度、验证情况和最终状态与实际一致，没有把未完成或未验证的事项写成已完成。