用途:让仓库文档成为对实现、意图和剩余工作的连贯记录;为每个持久事实和可变状态确定唯一权威归属,其他阅读路径通过链接指向它,并优先删除过期或重复内容,同时保留理解、理由、运维或决策所需的细节。
范围:不指定范围时覆盖仓库内全部活跃文档;指定变更、路径、主题、计划、子系统或对比时,仅覆盖该起点及其必要文档影响(归属文档、相关计划与状态记录、导航和交叉引用),不盘点整个仓库。针对变更时使用既有变更集,未指定则用当前已暂存、未暂存和未跟踪的变更;若无有意义的变更集,应先解决边界问题,而不是用无关历史替代。可包含文档专用导航与配置;源代码仅作为证据,不在编辑边界内。归档、生成输出、供应商文件和依赖被排除;保留不可变历史,同时修正活跃状态表述或其指向路径。可信的无关冲突记录下来待跟进,不扩大范围。
区分声明:需分别可读——实现现实(经代码、配置、测试、命令或发布验证的行为与运维边界)、目标设计(最新确认方向支持的已选定、提议或未决的未来行为)、交付状态(按仓库既有规划约定标注的已完成、进行中、受阻、推迟和下一步工作)。已接受的设计不等于已实现行为;仅有源代码实现不能证明验证、发布、支持、授权或生产就绪。用清晰的文档框架、时态或简明状态图表达区分,避免每句重复限定。
协调文档:阅读范围内每份文档,对照相应证据核实其重要声明;恢复决策与有用理由;暴露未解决冲突而非臆造意图。独立领域可委派,由协调者负责覆盖范围与整合结果。为每份文档选择用途、受众、范围和生命周期;保留已适用的简洁文档;当归属或阅读路径需要时重写、合并、拆分、移动或删除;仅在存在独立持久职责时新建文档。改动这些文件时保留工具可识别的指令发现与优先级。创建、重写、拆分、合并或移动 ARCHITECTURE.md 时,先阅读架构文档指南;保持目标架构框架可见,让计划拥有交付顺序和剩余工作,而不是把架构变成第二路线图。
应用结果:直接应用一致结果,在合适位置整合更新,删除被取代的陈述和类似记录的历史,修复受影响的链接、命令、术语和导航;即使原措辞或位置不再合适,也保留有用意图。仅在单独要求时才暂存、提交和推送。
完成标准:通读最终文档,检查受影响的链接、路径、示例和命令,搜索过期术语与冲突声明;将无持久用途的易变计数替换为稳定事实或来源指针。检查双向衔接:已完成工作进入当前状态文档和进度记录,未完成设计保持明显未实现;直接入口概览必须与详细计划指向同一权威状态。说明每份范围内文档与冲突,运行相关可用检查,并修复由重写导致的失败。报告有意义的更正、归属或拓扑变化、验证情况和未解决限制。当范围内文档一致,读者能找到存在什么、意图是什么、还剩什么时结束。
限制:仅显式调用时执行;缺少信息处未提供更多细节。