zhangrh.shop、ShotMarker、frontend-observability-server，两段 Codex 讨论，以及最终规范文件PROJECT_DOCUMENT_GOVERNANCE.md，文件内标注版本 1.5、制定日期 2026-08-19425823d0c893c4894bdc04abcdc5d9efcfc6be1251180e5137cb06b7ffd3e8bf重要说明：本报告把“项目和对话中的可观察记录”与“对这些记录的解释”分开。凡是无法从给定对话、最终文件或本地 Git 历史支持的内容，一律不写成事实。
这套方案不是一次性从抽象原则推导出来的，而是在一连串真实问题、一次明显偏重的治理实验、两轮有取舍的讨论，以及一次真实误读事故中逐步收敛出来的。
它解决的核心矛盾可以概括为：既要让人和 Agent 很快知道“项目现在是什么”，又要保留变更为什么发生、如何执行、如何验证的上下文；同时不能让历史、过程和治理机制反过来淹没当前结论。
最终得到的不是单纯的三个目录，而是四种不同职责：
current 负责清楚地说明现在；
changes 负责承载尚未结束的变更材料；
archive 负责保存已经结束且仍值得查阅的过程；
Git 负责保存文件本身逐版本如何变化。
整个形成过程存在两条彼此交织的反馈链：
三个项目分别提供了不同的压力测试：
| 项目 | 可观察到的主要压力 | 对最终方案形成的贡献 |
|---|---|---|
zhangrh.shop |
文档数量大、部署说明重复、旧事实残留、公开与私有事实分散、跨项目 Track 信息 | 证明需要入口、当前事实提炼、Git 与 archive 分工、公开/私有和跨仓库单一事实源 |
frontend-observability-server |
候选方案与当前结论混杂、接口命名冲突；随后又出现元数据、目录、校验脚本过多；current 技术正文膨胀 | 提供了从复杂治理到简单治理的完整反例与修正轨迹，并直接支撑 current 边界、稳定文件名、事实与决定分离 |
ShotMarker |
单一状态页承担过多职责；存在一个 563 行仍活跃的 spec；大量已结束 spec/plan；外部发布状态会变化 | 证明需要按主题拆分 current、区分 active Change 与历史、不能把 current 的行数规则套到 spec、外部状态必须带验证日期 |
最值得注意的是：最终规范中若干看起来像“预防性设计”的条款，其实来自已经发生的问题。例如，“300 行只适用于单份 current”不是凭空补充，而是 2026-08-20 一个 Agent 已经把该限制错误套用到 spec 之后才被强化；“archive 按月”也不是预先假设，而是用户在实际铺开 archive 后直接反馈目录太大。
本报告使用以下标记：
+08:00 时间。ShotMarker 在最终核对时有两个未跟踪的截图目录；它们与文档治理历史无关，未纳入因果分析。frontend-observability-server 在最终核对时本地 master 比 origin/master 领先 1 个提交；报告以本地可见的治理提交为准，不据此推断远端状态。| 时间（UTC+8） | 事件 | 证据类型 | 对方案的意义 |
|---|---|---|---|
| 2026-07-29 15:13—15:41 | zhangrh.shop 合并重复项目/部署文档，修正文档事实边界，删除 30 份旧设计/计划并依赖 Git 恢复 |
B | 最早可见的“当前说明、历史过程和 Git 分工”实践前因 |
| 2026-08-11 17:09—18:06 | frontend 建立六类目录、三维元数据、状态头、晋升流程和 Ruby 校验脚本 | B | 形成一个可完整观察的复杂治理实验 |
| 2026-08-13 17:26 | frontend 删除多维元数据、空目录、入口占位和校验脚本，只保留 current/archive 业务语义 | B | 明确发生“治理机制瘦身”，目录本身成为状态表达 |
| 2026-08-16 | ShotMarker 设计单一状态页；最终状态快照达到 247 行 | B | 验证“当前状态入口”价值，也暴露单页职责过多的趋势 |
| 2026-08-18 15:38—16:24 | frontend 将三份 current 技术正文从 1,464 行大幅精简，并把 current 日期名改为稳定语义名 | B | 直接支撑 current 简洁、单一事实源、按边界拆分、无日期命名 |
| 2026-08-19 10:24—11:26 | 三个项目先后迁移到共同的 current/changes/archive 基线；补充公开/私有及跨仓库边界 | B | 通用方案首次在三个不同项目上系统落地 |
| 2026-08-19 11:30—14:05 | 第一段对话审查并形成 1.2—1.5：可信度分流、中文 AGENTS、按月 archive、current 300 行 | A+B | 用户直接取舍和规范版本演进最完整的一段 |
| 2026-08-19 14:32—15:57 | 三个项目继续对齐按月归档、可信度和跨仓库边界 | B | 规则从通用文档反向传播到项目实践 |
| 2026-08-19 14:55—15:14 | 第二段对话否决审批/元数据/自动化等过重建议；明确 Prompt 确认即决定；澄清 spec/plan 非强制 | A+B | 把方案的“轻量、按需、用户确认”边界写实 |
| 2026-08-20 12:07—12:10 | 用户报告 Agent 把 300 行错误套到 spec；规范加入目录作用域原则和显式反向约束 | A+B | 从真实误读中补上“规则不得跨目录类推” |
| 2026-08-20 13:13—14:28 | 审计三个项目的入口文档；六份入口需要补强；三项目隔离修改、合并、测试并由独立 reviewer 复核 | A+B | 最终规则完成跨项目传播和可执行性验证 |
zhangrh.shop 的文档堆积与清理zhangrh.shop 的 2026-07-29-project-cleanup-spec.md 记录了当时的仓库审计结果：
README.md；/legacy-h5/ 写成当前服务；docs/superpowers 中已有 30 份历史设计和计划，共 10,499 行。这是直接的 Git 文档事实，位置为 docs/archive/2026-07/2026-07-29-project-cleanup-spec.md:3-20。[B｜可观察事实]
当天三个提交显示了实际处理方式：
5f737a7（15:13，docs: 重整项目与部署文档）修改 11 个文件，319 行新增、812 行删除；把三份重复部署文档合并为一个入口，并整理项目说明。6ed9087（15:23，docs: 修正文档事实边界）继续纠正文档中什么属于当前事实。846cba2（15:41，chore: 删除废弃脚本与历史过程文档）修改 34 个文件，删除 11,073 行，其中包括前述 30 份历史过程文档；设计明确说明这些文件仍可由 Git 历史恢复，见同一 spec 的 115—120 行。[B｜可观察事实]能够确定的是：在最终规范形成前，项目已经真实经历过“当前入口缺失、重复文档、过时事实、历史过程大量堆积”的问题，也已经使用“删去工作树中的历史文件、依赖 Git 恢复”的办法减负。[B]
可以合理推断，这段实践构成了最终规则“Git 保存逐版本变化”“current 不保存提交日志和逐版本变化”的经验前因；二者解决的是同一类负担。[C｜受限推断]
但不能据此断言：用户在 7 月 29 日已经完整想出了 current / changes / archive 三态模型。Git 只能证明做过什么，不能证明当时尚未写下的完整方案已经存在。最终规范后来又修正了 7 月做法：迁移时应优先移动和提炼，不能为了干净删除仍有历史价值的材料；也就是说，最终方案不是简单复刻“全部删除、交给 Git”，而是进一步区分了两类历史：
frontend-observability-server 的复杂治理实验2026-08-11 的 document-governance-transition-spec 记录了六份设计/决策/评价文档中的冲突：
/v1/metrics、/v1/web-vitals、/v1/reports 三种名称；/livez、/readyz、/healthz、/health/live、/health/ready 五套表达；这些内容可直接定位到 docs/archive/2026-08/2026-08-11-document-governance-transition-spec.md:3-14。[B]
这里首次清楚呈现了最终方案要解决的几个核心问题：当前与历史混写、多个事实源互相矛盾、尚未实现的设计被误读为现状、读者不知道先读什么。[C，基于上述 B]
这份过渡设计没有立刻走向最终三态，而是建立了一个更复杂的体系：
current / working / decisions / archive / tdc / evidence
并要求每份文档同时声明三个维度：
type：discussion、spec、adr、validation、retrospective、evidence、governance；status：draft、proposed、accepted、superseded、archived；authority：implementation、decision、informative。它还规定标准状态头、四阶段迁移、晋升 current 的条件、未决项结构、旧路径迁移说明和独立 Git 提交。目录与元数据可见于该 spec 的 84—170 行。[B]
随后从 c6327e8、0a29f60、9439881、fcea58e 到 c43e56d，仓库分阶段建立了这套体系；最终还有 scripts/check-docs.rb、治理头、结构化示例和归档正文哈希检查。c43e56d 单次增加 444 行。[B]
这一步非常重要，因为后来的“不要元数据、不要空占位、不要治理脚本”不是抽象的 YAGNI 口号，而是对一套已经实际建立过的机制进行回撤。[C]
34e5085（docs: 精简项目文档为当前与归档结构）修改 30 个文件，只新增 69 行却删除 860 行。对应 spec 明确写道：
current/ 和 archive/ 两种业务语义；type、status、authority 或审阅/执行状态元数据；scripts/check-docs.rb；证据位于 docs/archive/2026-08/2026-08-13-simplify-document-structure-spec.md:3-12,67-93。[B]
这次精简还不是最终方案：当时仍保留工具专属的 superpowers/，current 中甚至包含“现行实施计划”，普通文档仍使用日期前缀，也还没有 changes。但它确立了最终方案的一个关键方向：优先让目录本身表达生命周期，不再给每份文档附加一套治理状态机。[C]
2026-08-18 的 simplify-current-document-content-spec 开头明确记录：三份 current 技术文档仍有 1,464 行，并同时描述当前协议、浏览器 SDK、未来多应用平台、Histogram 迁移、测试实现、容量目标、Dashboard、告警和验证记录，当前事实与未来预案仍然混在一起。证据位于 docs/archive/2026-08/2026-08-18-simplify-current-document-content-spec.md:3-7。[B]
这说明“把文件移进 current”本身不能保证 current 清晰；必须继续约束内容边界。[C]
该设计比较了三种做法：
对应证据为同一 spec 的 34—59 行。[B]
三个连续提交显示了实际压缩规模：
| 提交 | 文档 | 变更规模 |
|---|---|---|
15eaaa4 |
架构与范围 | 56 行新增、193 行删除 |
2877060 |
指标上报协议 | 106 行新增、525 行删除 |
84a2427 |
验证与运维 | 96 行新增、490 行删除 |
压缩不是把内容挤成长段落，而是删除无现行业务需求或无实证支撑的未来平台、通用迁移框架、accepted/observed 状态机、SDK 固定算法、精确但未验证的运行阈值，以及重复的协议/流程说明；spec 的 110—169 行逐项列出了这些删除与写作规则。[B]
这一实践直接解释了最终规范为何同时规定：current 只保留理解现状所需的信息；一段一个主题；详细背景链接 changes/archive；按变化节奏、证据来源和兼容边界拆分；不能靠长段落绕过行数限制。[C]
2026-08-18 16:24 的 1ebd1b8 移除了 current 文档日期前缀。对应设计的理由非常明确：
docs/current/ 是持续更新的现行事实，不是按日期冻结的快照；证据位于 docs/archive/2026-08/2026-08-18-use-stable-current-document-names-spec.md:3-19,28-37。[B]
这与最终规范的“current 使用稳定、无日期、简短清晰的名称；changes/archive 使用日期”几乎形成一一对应的实践来源。[C]
2026-08-16，ShotMarker 曾设计把 docs/current-codebase-status.md 作为唯一内部状态页：顶部写当前结论，底部只保留少量最近进展，更早历史交给 Git。该设计明确说状态页不替代 PRD、设计、计划或提交历史。证据位于 docs/archive/2026-08/2026-08-16-project-status-document-spec.md:5-26。[B]
这份设计已经包含最终方案的若干思想：单一当前入口、当前结论优先、少量历史、变化外部状态要标日期、Git 承担旧历史。但实际形成的状态快照有 247 行，固定十个部分，同时覆盖总体状态、功能、进行中工作、测试、风险、下一步、发布检查和最近进展。[B]
三天后的治理迁移没有继续维护一份包办所有内容的状态页，而是把它归档，并拆出 status.md、product.md、architecture.md、quality.md、release.md 等稳定主题。可合理推断，这次变化不是否定“状态入口”，而是把状态入口降为摘要和导航，把不同证据来源、变化节奏和兼容边界交给不同 current 文件。[C]
第一段指定对话在 2026-08-19 11:30 才开始，Assistant 读取到的文件已经是 1.1；而三个项目的迁移最早从当天 10:24 开始。因此，通用规范 1.0/1.1 的最初草拟和当天上午迁移所依赖的另一段会话，不在用户本次给出的两段对话中。[B]
我们仍能从 1.1 快照和 Git 产物确定它当时已经包含什么：
current / changes / archive 三态；AGENTS.md 与 docs/README.md 的入口职责；第一段会话的原始工具输出完整捕获了这份 314 行的 1.1。[B]
因此可以说，最终方案的骨架在 11:30 前已经存在；但不能从现有材料声称“某一条具体讨论直接产生了三态模型”。本报告只把三个项目更早的实践写成可验证前因。[证据边界]
zhangrh.shop：公开/私有和跨仓库边界a789241（10:24，docs: 重整项目文档治理）建立了 AGENTS.md、docs/README.md 和三份 current 文档，把 9 份 spec、6 份 plan 移到 archive，并建立 changes。提交规模为 472 行新增、212 行删除。[B]
其迁移计划把“生命周期”和“可见性”明确分开：公开仓库维护代码、产品、质量和部署契约；私有仓库维护基础设施、生产配置和外部验证；凭据不进入任何仓库。计划还要求保留有价值的事实和历史，不以清理为由删除；见 docs/archive/2026-08/2026-08-19-project-document-governance-migration-plan.md:5-19。[B]
这一设计明显回应了 zhangrh.shop 的现实结构：同一项目事实分布在公开代码仓库和 docs/private.local 独立 Git 仓库中。它最终演化为规范 2.1 节的几条规则：生命周期不表示可见性、每个仓库只维护权限边界内的三态、每项事实只有一个当前来源、公开文档在私有仓库不可用时仍应可读。[C]
985ea14（11:10）继续把 automation、backend、track 等当前主题纳入 current，并删除重复入口；f89c1ae（ShotMarker，11:22）记录私有文档仓库边界，2537486（11:23）从公开 archive 收敛私有运维细节。[B]
这些提交说明，公开/私有规则不是只写在通用规范中的假设，它已经用于迁移真实文件和缩减公开历史内容。[B]
ShotMarker：active Change 与历史材料分开ef5bde0（10:35，docs: 统一项目文档治理并补充埋点事实）修改 40 个文件，建立文档入口和多份 current 主题，把 247 行旧状态快照、PRD、已结束的 spec/plan 归档；同时把仍未实现的语音口令设计保留为 docs/changes/2026-07-29-ios-voice-command-marking-spec.md。[B]
对应治理 spec 明确写道：“当前没有对应 plan，不创建空计划”，见 docs/archive/2026-08/2026-08-19-document-governance-spec.md:65-74。这说明“一个 Change 可以只有 spec，不能为满足模板创建空 plan”在第二段对话正式澄清“并非每个变更都强制 spec+plan”之前，就已经有项目实践。[B]
这也是后来“current 不规定固定文档清单”“不为满足模板创建空文件”“如果同一个 Change 生成 spec 和 plan，则共享日期/topic”等规则的直接实践背景之一。[C]
5d87879（11:26，docs: 完成项目文档治理迁移）建立 AGENTS.md、统一的 docs/README.md、changes/.gitkeep，并把工具专属目录里的 7 份设计/记录和 2 份计划迁到 archive。[B]
其对齐记录列出的迁移前差异包括：入口仍在 docs/current/README.md、缺少 Agent 读取顺序、结束材料还在工具专属目录、跨仓库权威范围不清、尚未实现的契约容易被现在时误读。见 docs/archive/2026-08/2026-08-19-document-governance-alignment.md:3-22。[B]
值得注意的是，这次迁移没有为了匹配模板新增 current 文件，也没有创建虚假 spec/plan，只用 .gitkeep 保持空 changes 目录。它把 8 月 13 日的“current/archive”简单化继续推进为最终的“current/changes/archive”，其中 changes 只承载真实存在且未结束的材料。[C]
第一段对话原始日志共有 470 个 JSONL 事件、11 个用户消息；任务 ID 为 01a01811-7b6a-75b3-b079-d7b644796aa1。以下时间均为 UTC+8。
11:30，用户要求审查规范。Assistant 在 11:31 提出七类问题，其中包括：
这些是 Assistant 的审查意见，不等于用户认可。[B｜对话事实]
11:44，用户逐项取舍：
private.local 承担；11:45 的补丁把版本从 1.1 升到 1.2：
这一步不是简单调整“证据优先级”，而是承认项目同时存在两类不同真相：描述“已经实现什么”的经验事实，和描述“当前必须以什么为准”的规范决定。最终规范第 7 节完整保留了这个分流。[C]
11:58，用户询问能否把 AGENT.md 规则改为中文。Assistant 核对后说明正文可以中文，但标准文件名应是复数 AGENTS.md。12:01 用户要求执行；第 11 节可复用规则被完整翻译为中文，路径、文件名和语义保持不变。[A+B]
这一修改没有改变治理模型，但影响了方案的可迁移性：最终规范不仅描述原则，还附带一段可以直接复制到项目中的中文 Agent 工作规则。[B]
13:45，用户直接反馈：如果全部放入 archive，文件铺开非常大，并提出使用 2026-07、2026-08 月份目录。[A]
Assistant 比较了继续扁平、按年和按月三种方式，推荐：
YYYY-MM 一层；用户在一次输入纠正后于 13:47 明确确认。13:48—13:49 的补丁把版本 1.2 升到 1.3，并同步修改标准结构、README 职责、changes 完成规则、archive 职责、命名、生命周期、迁移、日常检查和 AGENTS 示例。[A+B]
这条规则具有非常清晰的形成因果：问题和候选方案由用户直接提出，确认后立即进入规范。它是本次材料中最强的一类来源证据。[A+B]
13:56，用户提出三项 current 要求：
13:58，用户进一步指定：超过 500 行时应考虑如何合理拆分，不能通过合并长段落规避。[A]
13:59—14:01 的补丁形成 1.4，把这些要求同时写入 current 定义、边界原则、简洁性章节、维护检查和 AGENTS 示例。[B]
这里的重点不只是数字，而是规则意图：行数是推动合理边界的信号，不是压缩排版的目标。这一意图后来继续保留在 300 行版本中。[A+B]
14:02，用户追问 500 行还是 300 行更合理。Assistant 推荐 300，理由是 current 是快速了解现状的入口；300 行已经足够表达较完整的事实、决定、风险和证据；接近 500 时往往混入多个独立主题；规范允许多份 current，因此不需要设置“建议 300、上限 500”双层规则。[B｜Assistant 建议]
14:04，用户明确确认 300 行。[A]
随后补丁把版本升到 1.5，并在正文、维护检查和 AGENTS 示例三处把 500 统一为 300。[B]
因此，300 不是从某个外部标准抄来的强制数字，而是在用户先提出 500、要求合理拆分、再比较 300/500 后做出的明确选择。[A+B]
通用规范变化后，三个项目在 8 月 19 日下午继续对齐：
zhangrh.shop295c3ca（14:32）把 16 个归档文件迁入月份目录；dd83c10（15:57）更新中文治理规则和入口；1c24f38（15:57）区分当前事实与有效决定；a0470f7（15:57）明确 Track 跨仓库权威边界，把 ShotMarker 客户端埋点细节指向 ShotMarker 自己的 current。[B]这组提交把规范中的三个抽象原则变成项目事实：按月 archive、事实/决定分流、跨仓库一个权威来源。[B]
frontend-observability-server9dee37a（14:40，docs: 对齐项目文档治理规范 v1.5）把 24 份 archive 文件迁入 2026-07/2026-08 月份目录，并更新入口与可信度规则。对应 spec 还记录：
/livez；/readyz、指标接收/导出、Registry、生产保护、CI、容器和部署仍未实现；证据位于 docs/archive/2026-08/2026-08-19-document-governance-v1-5-spec.md:76-84。[B]
这正是“实现事实”和“有效决定”分流在真实项目中的示范：current 不需要在二者之间二选一，而应同时说清楚已实现部分、仍有效的契约和实际差距。[B]
ShotMarker41bfda2（15:48）按新版规范把 archive 改为月份目录，并更新事实/决定规则；提交修改 34 个文件。[B]
项目中仍活跃的语音口令 spec 有 563 行，却合理保留在 changes。这个事实后来成为验证“300 行只属于 current”时最直观的反例：长 spec 不等于违反 current 简洁性规则。[B]
第二段对话原始日志共有 930 个 JSONL 事件、9 个用户消息；任务 ID 为 01a018cd-eeb6-7de0-a626-e3f6e45c484f。该会话跨越 2026-08-19 和 2026-08-20。
14:55，用户再次要求审查。Assistant 最初给出约 8/10，并再次建议批准权、状态流转、文档元数据、自动检查和全局 Change ID。[B｜对话事实]
15:05，用户逐项质疑：
15:08，Assistant 纠正了自己的评审尺度：在“用户 + Agent”的协作里，用户在 Prompt 中的确认本身就是授权/确认；Superpowers 并不要求每个变更都产出 spec 和 plan；之前提出的审批、元数据、状态机、CI、全局 ID 等建议应撤回。[B]
这段对话使最终方案的简洁性不再只是 frontend 8 月 13 日的一次项目实践，而成为用户明确表达的治理原则：不为假想的组织流程添加额外层级，当前协作中由用户明确确认决定即可。[A+B]
用户要求原句加入：
用户在任务中明确确认的决定视为已经作出；Agent 不得将提议、推测或未确认方案写成有效决定。
15:11 的补丁把这句话加入 current 规则。[A+B]
这句话补上了“决定何时成立”的最小闭环，同时避免引入 owner、approver、状态字段或审批系统：决定的有效性来自用户在任务中的明确确认，Agent 只能记录，不能自行把建议升级为决定。[C]
用户随即追问：现有文档是不是要求所有变动都在 changes 生成 spec 和 plan？其真实意图只是“如果变动过程中生成了这些文件，就放到 changes”。[A]
Assistant 复查后确认：4.4 节接近本意，但 6.1 节的无条件流程确实容易被读成强制每次创建 spec 和 plan。[B]
用户确认最小修改，15:13 补丁完成三处澄清：
这不是放弃 spec/plan，而是把“材料类型”和“生成义务”分开：有 spec/plan 时必须按统一生命周期治理，没有生成时不补造空文件或事后伪造过程。[C]
这一点也与三个项目已有事实一致：ShotMarker 的 active Change 只有 spec；frontend 的对齐 spec 明确拒绝为已经结束的测试改动倒填事前 spec/plan；空 changes 只保留 .gitkeep。[B]
用户在第二段对话中贴出一个实际错误：Agent 把“单份 current 不超过 300 行”误读为 spec 也要控制在 300 行内；用户还说明，有的项目执行时把 300 行套到了 archive/changes 的 spec 和 plan，而这不是原意。[A]
Assistant 诊断为：原文只用正向措辞说明 current 的限制，却没有同时写出目录专属规则不能向其他目录类推；Agent 仍可能把一个醒目的数字扩展成全局文档规则。[B]
用户要求修改后，实际补丁加入四层防线：
同时，spec/plan 的拆分标准被明确为“变更范围和内容边界”，不是行数；质量标准是完整、无歧义、足以支持实施与验证。[B]
这一步揭示了最终规范写法上的一个重要演进：只写“某规则适用于 A”不一定足够；对于很容易被 Agent 泛化的规则，还要写“不得用于 B/C”，并在入口规则中重复关键反向约束。[C]
用户要求按最新规则核对三个项目，尤其是 AGENTS.md、根 README 和 docs/README.md。[A]
审计结果是：没有任何文件明确写成“spec/plan 不得超过 300 行”，所以当时不存在已经写错的硬规则；但三个项目各自的 AGENTS.md 和 docs/README.md 共 6 个入口文件都缺少最新版的显式反向约束，仍有再次误读的风险；三个根 README 无需修改。[B]
行数核对还提供了现实验证：
zhangrh.shop 的 current 最大 124 行；后两项尤其证明：若把 300 行全局化，会把本来合法、需要完整支持实施的变更材料错误判为违规。[B]
用户要求三个项目分别用隔离 worktree 修改、合并到 main/master，并再用三名独立 reviewer 检查。[A｜历史执行授权]
最终本地合并提交为：
| 项目 | 分支 | 提交 | 结果 |
|---|---|---|---|
zhangrh.shop |
main |
be6864c |
两份入口补充目录作用域、current-only 300、spec/plan 非强制等规则 |
ShotMarker |
main |
4c64ca2 |
同上；保留 563 行 active spec 的合法性 |
frontend-observability-server |
master |
9301ca7 |
同上；治理提交在新的 metrics-registry 基线上安全重放 |
执行中还有两项有据可循的安全处理：
三名未参与实现的 reviewer 都报告无 Critical、Important 或 Minor 问题。历史会话记录的验证结果为：
zhangrh.shop：194 项测试通过；这些测试不能证明治理思想“绝对正确”，但可以证明最终澄清已被一致写入三个项目入口，且落地没有破坏当时的项目基线。[证据边界]
最终模型只问一个问题：这份材料现在处于什么生命周期？
frontend 的复杂实验曾用“类型、状态、权威”三个维度同时分类，后来明确删除；ShotMarker 的迁移则证明产品、架构、质量、发布等只是 current 的项目内主题，不是全局固定分类；changes/archive 也不再按 spec、decision、incident、topic 等继续建目录。[B]
因此，最终方案选择“少量稳定语义 + 项目自行决定主题”，而不是建立一个覆盖所有文档种类的分类学。[C]
形成过程中出现过两个看似矛盾的实践：
zhangrh.shop 删除 30 份历史设计/计划，理由是 Git 可恢复；最终规范把这两者统一起来：
这是一种“版本历史”和“知识材料”分工，而不是“Git 或 archive 二选一”。[C，基于多个 B]
最终 current 规则来自多轮实践叠加：
因此，300 行只是完整 current 设计中的一个护栏。它不能脱离“完整、可独立维护的当前结论”“不靠长段落规避”“按范围与证据合理拆分”单独使用。[C]
最初的统一优先级把代码放在 current 之前，适合判断实现事实，却会产生一个危险推论：只要代码没实现，已经确认的决定就自动无效。
用户接受的 1.2 修正把问题拆开：
| 要回答的问题 | 最高依据 | 冲突如何处理 |
|---|---|---|
| 现在实际实现、构建、发布或上线了什么？ | 当前代码、测试、构建、当次外部验证 | 重新核验并修正 current 中的实现事实 |
| 当前已经生效的决定、契约或政策是什么？ | current 中明确记录且仍有效的内容 | 代码不一致时保留决定，同时展示实现差距并作为缺陷 |
frontend 在 9dee37a 中把 /readyz、指标接口和部署等“仍未实现”与“V1 决定仍有效”同时写入 current，是这一原则最具体的项目实例。[B]
第二段对话再补充决定来源：用户在任务中明确确认即视为已经作出；Agent 不得把建议、猜测或未确认方案升级为决定。这以最小规则解决了“谁让决定生效”，没有引入审批系统。[A+B]
项目历史同时显示两件事：
最终规范因此规定“如果生成，就放 changes 并在结束后归档”，而不是“每次必须生成”。同一个 Change 同时有两份材料时才要求共享日期/topic。是否拆分依据内容和范围，不依据 300 行。[A+B]
这也解释了为什么 changes 必须保持简单和扁平：它是活动材料集合，不是一个强制工作流状态数据库。[C]
flat archive 在初始模型中是为了避免每个 topic 建小目录；用户实际铺开后发现文件太多，才提出月份层。最后选用 YYYY-MM，是对两种需求的折中：
“按需建月份、不建更深目录”保留了 8 月 13 日精简实验中的克制原则。[A+B+C]
current / changes / archive 不等于“公开/内部/机密”。zhangrh.shop 和 ShotMarker 的真实资料跨公开仓库与 private.local 独立仓库，促使规范明确：每个权限边界内都可以有自己的三态，但每项事实只能有一个当前权威来源。
最终规则既防止把私有基础设施值复制到公开文档，也要求公开仓库在私有仓库不可用时仍能说明公开代码、接口和部署契约。这不是把公开文档写成空壳，而是用摘要和引用控制重复。[B+C]
“简单”在这里不等于没有规则，而是只保留已被真实问题证明必要的规则：
所以最终方案的简洁不是“少想一步”，而是把规则增长绑定到已发生的问题，并要求新增规则能通过项目实践说明其价值。[C]
| 未采用方案 | 出现位置 | 没有采用的直接依据 | 最终替代 |
|---|---|---|---|
| 负责人、批准状态、生效日期、复审周期、修改流程、例外审批 | 第一段初审；第二段初审再次出现 | 用户明确认为过于复杂，当前修改均通过 Prompt 且 Git 有历史 | 用户在任务中明确确认即为决定；Git 记录修改 |
文档 type/status/authority 三维元数据 |
frontend 8 月 11 日实际实施；第二段初审又被建议 | frontend 8 月 13 日明确删除；用户再次称元数据过度设计 | 目录位置表达生命周期；current 内文字区分事实与决定 |
working/decisions/tdc/evidence 多业务目录 |
frontend 8 月 11 日 | 8 月 13 日精简提交删除空目录、占位入口和多维结构 | current/changes/archive；项目真实需要的资料按内容放置 |
| 全局 Change ID、完整状态流转 | 第二段初审 | 用户认为后续建议过度设计；Assistant 收回 | 日期 + topic；同一跨仓库 Change 各仓库分别闭环 |
| 文档 CI 自动检查作为默认要求 | frontend 曾有 scripts/check-docs.rb；第二段初审再建议 |
8 月 13 日删除；用户称自动检查过度设计 | 每次任务做与风险相称的链接、格式、工作区和测试核验 |
| 每个需求/变动必须生成 spec 和 plan | 原 6.1 无条件流程容易造成该解读 | 用户明确说明只治理已生成材料；实际项目存在只有 spec 或无文件的 Change | 条件式生成；有文件则放 changes，结束后归档 |
| 为没有 plan 的 Change 创建空 plan | 模板化结构可能诱发 | ShotMarker 治理 spec 明确“当前没有对应 plan，不创建空计划” | 不为满足模板创建空文件 |
| archive 完全扁平 | 1.1/1.2 初始方案和最初项目迁移 | 用户实际反馈文件铺开太大 | 只增加 YYYY-MM 一层，按需创建 |
| archive 只按年份 | 第一段 13:45 的比较候选 | 按年仍可能在一个目录堆积过多，用户确认按月 | YYYY-MM |
| archive 按 topic/type 建更深层目录 | 早期复杂体系和常见分类候选 | 用户希望保持简单；按月方案明确禁止 | 月份目录 + 可检索文件名 |
| current 单份 500 行 | 用户最初提议，1.4 实际写入 | 用户比较后明确确认 300 | 单份 current 300 行，并按边界合理拆分 |
| “建议 300、硬上限 500”双层规则 | 第一段比较时的可能做法 | Assistant建议避免双层复杂度，用户确认统一 300 | 单一 300 行护栏 |
| 把 300 行用于所有文档 | Agent 的真实误读 | 用户明确指出错误并要求修改 | 目录作用域原则 + explicit negative；spec/plan 按内容完整性拆分 |
| current 使用日期前缀 | frontend 8 月 13 日精简后仍保留 | 8 月 18 日设计说明持续更新文档不是日期快照 | 稳定、无日期、语义化文件名 |
| 所有技术 current 合成一个大文档 | frontend 8 月 18 日比较候选 | 会混合架构、协议和运维，变化时误触无关内容 | 按事实源、变化节奏和证据边界拆分 |
| 只做局部删句 | frontend 8 月 18 日比较候选 | 不能消除同一规则在多处重复定义 | 按事实源重构，每条规则一处完整定义 |
| 单一 ShotMarker 状态页包办全部当前信息 | ShotMarker 8 月 16 日实践 | 8 月 19 日迁移将快照归档并拆成多个主题 | status.md 做摘要入口，其余 current 分责 |
| 为已结束改动倒填事前 spec/plan | frontend v1.5 对齐时明确列为范围外 | 会伪造形成过程 | 只补诚实的历史完成记录 |
| archive 中保存 current 的每个历史版本 | 可能的历史保留做法 | 规范从一开始就把逐版本变化交给 Git | archive 保存独立历史材料，Git 保存逐版本 diff |
以下“来源”不是声称每一行都由某一条证据机械生成，而是列出该章节最直接的可追溯前因、明确讨论或实际修正。
| 最终规范位置 | 最终规则主题 | 主要可追溯来源 | 证据强度 |
|---|---|---|---|
| 1—5 | 名称、1.5 标签、日期、适用范围 | 第一段 1.1→1.5 补丁；最终文件 | B；注意 8 月 20 日继续修改但未升版 |
| 7—16 | 目标：快速回答现在、决定、活动变更、历史；文档不替代代码/测试/Git | 三项目问题与迁移入口；1.1 已存在 | B+C；最初文字形成对话缺失 |
| 18—28 | 三态模型；Git 保存逐版本变化 | 1.1 快照；zhang 7 月清理；frontend 8 月结构精简；三项目迁移 | B+C |
| 30 | 目录专属规则不得跨目录类推 | 8 月 20 日用户报告 300 行真实误读及实际补丁 | A+B，直接因果最强 |
| 32—43 | 生命周期与可见性分开；多仓库、公开/私有、单一事实源 | zhang 8 月 19 日迁移计划；ShotMarker 私有边界提交；Track 跨仓库提交 | B+C |
| 45—65 | 标准结构；changes 扁平；archive 按月且无更深层 | 1.1 骨架；第一段 13:45 用户提出月份并确认 | A+B |
| 67 | current 不预设数量/主题，不建空文件 | frontend 8 月 13 日删除模板/占位；ShotMarker 无空 plan；三项目主题不同 | B+C |
| 71—81 | AGENTS 职责 | 三项目迁移时新增入口；第一段中文化 | B |
| 83—91 | docs/README 简短入口职责 | 三项目迁移和对齐记录 | B |
| 93—113 | current 允许/禁止内容；事实/决定清晰可靠；实现差距 | frontend 冲突与内容精简；第一段 1.2 和 1.4 补丁 | A+B |
| 115 | 用户明确确认即为决定；Agent 不得升级提议 | 第二段 15:11 用户原句和实际补丁 | A+B |
| 117—133 | current 边界、稳定无日期/常用词、证据和验证日期 | frontend 8 月 18 日按事实源重构和稳定命名；ShotMarker 外部状态；第一段 current 要求 | A+B+C |
| 135—152 | changes 保存活动材料；spec/plan 条件式生成；相同日期/topic | ShotMarker 只有 spec；第二段 15:11—15:14 用户澄清和补丁 | A+B |
| 154 | spec/plan 不受 300 行限制；按内容和范围拆分 | 8 月 20 日真实误读和补丁；项目中 563 行 spec、1,434 行 plan | A+B |
| 156 | Change 结束后不留在 changes，按文件日期归档 | 1.1 生命周期；第一段按月修改；三项目迁移实践 | A+B |
| 158—171 | archive 内容类型、月份、非当前事实源 | 三项目历史迁移；第一段按月讨论；frontend 简化 | A+B+C |
| 173—192 | 日期/topic/后缀/工具无关命名 | 三项目迁移映射；frontend stable names；第一段月目录 | B+C |
| 194—220 | 代码/产品变更及非代码讨论生命周期 | 1.1 已有；第二段改为条件式材料；第一段按月路径 | A+B |
| 222—248 | 实现事实与有效决定分别取证，冲突为缺陷 | 第一段首轮审查、用户只接受此项、1.2 补丁；frontend 实际 gap 记录 | A+B |
| 250—267 | current 人类可读、300 行、合理拆分、历史判定问题 | frontend 1,464 行精简；第一段 500→300；8 月 20 日 scope 加固 | A+B+C |
| 269—283 | 迁移步骤；优先移动和提炼，不删除有价值历史 | 三项目 8 月 19 日迁移；对 zhang 7 月大规模删除实践的进一步修正 | B+C |
| 285—303 | 日常开始/完成检查 | 三项目迁移计划和实际验证；第一段/第二段同步补丁 | B |
| 305—329 | 可复用中文 AGENTS 规则 | 第一段 12:01 翻译；每轮规则同步；8 月 20 日三项目传播 | A+B |
| 331—338 | 四句最终原则 | 1.1 已存在，最终文件保留 | B；其首次创作过程不在所给对话中 |
zhangrh.shop：规模、重复、可见性和跨仓库它不是最清楚展示治理过度设计的项目，却是最能说明为什么需要治理的项目。7 月已经出现 30 份、10,499 行历史设计/计划，部署文档重复且包含过时服务；8 月又必须同时处理公开产品文档、私有基础设施台账和跨项目 Track 事实。
因此，它主要支撑：
frontend-observability-server：复杂度的完整摆动轨迹它对最终方案的影响最系统，因为同一个仓库先后展示了：
候选与当前混写
→ 多目录、多元数据、多阶段晋升、自动校验
→ 治理结构本身过重
→ current/archive 简化
→ current 正文仍膨胀
→ 按事实源重构并删除预设计
→ current 稳定命名
→ 引入 changes 形成三态
→ 事实与决定分流
→ 300 行作用域澄清
因此，它主要支撑：
ShotMarker 的价值在于它是一款包含 iPhone、Watch、发布流程和外部服务的产品项目，文档不只描述代码。单一状态页曾试图容纳整个项目，后来被拆成 status、product、architecture、quality、release；一个很长但仍活跃的语音命令 spec 与大量结束材料同时存在。
因此，它主要支撑：
为了避免把完整叙事写成“完整想象”，以下内容必须明确留白：
| ID | 证据 | 定位 |
|---|---|---|
D-FINAL |
最终规范快照 | /Users/runhaozhang/Desktop/PROJECT_DOCUMENT_GOVERNANCE.md；338 行；SHA-256 如文首 |
T1 |
第一段 Codex 原始会话 | task 01a01811-7b6a-75b3-b079-d7b644796aa1；本地 JSONL /Users/runhaozhang/.codex/sessions/2026/08/19/rollout-2026-08-19T11-29-54-01a01811-7b6a-75b3-b079-d7b644796aa1.jsonl |
T2 |
第二段 Codex 原始会话 | task 01a018cd-eeb6-7de0-a626-e3f6e45c484f；本地 JSONL /Users/runhaozhang/.codex/sessions/2026/08/19/rollout-2026-08-19T14-55-44-01a018cd-eeb6-7de0-a626-e3f6e45c484f.jsonl |
zhangrh.shop仓库：/Users/runhaozhang/Documents/project/zhangrh.shop
| ID | 提交/文件 | 证明内容 |
|---|---|---|
GZ-01 |
5f737a7 |
合并重复项目/部署说明；319+/812- |
GZ-02 |
6ed9087 |
修正文档事实边界 |
GZ-03 |
846cba2 |
删除旧脚本和 30 份历史过程文档；11,073 行删除 |
GZ-04 |
docs/archive/2026-07/2026-07-29-project-cleanup-spec.md:3-20,77-120 |
缺入口、重复、过时事实、30 份/10,499 行历史材料及 Git 恢复策略 |
GZ-05 |
a789241 |
建立共同三态入口，迁移 9 spec + 6 plan |
GZ-06 |
docs/archive/2026-08/2026-08-19-project-document-governance-migration-plan.md:5-19,73-157 |
生命周期/可见性、公开/私有、安全边界和迁移步骤 |
GZ-07 |
985ea14 |
统一更多 current 主题并删除重复组件入口 |
GZ-08 |
295c3ca |
archive 改为月份目录 |
GZ-09 |
dd83c10, 1c24f38, a0470f7 |
中文治理、事实/决定分流、Track 跨仓库权威边界 |
GZ-10 |
be6864c |
300 行 current-only、spec/plan 条件式等最终澄清进入项目 |
ShotMarker仓库：/Users/runhaozhang/Documents/project/ShotMarker
| ID | 提交/文件 | 证明内容 |
|---|---|---|
GS-01 |
docs/archive/2026-08/2026-08-16-project-status-document-spec.md:5-83 |
单一状态页、当前结论、少量最近历史、验证日期与固定十部分 |
GS-02 |
docs/archive/2026-08/2026-08-16-project-status-snapshot.md |
实际综合状态快照 247 行 |
GS-03 |
ef5bde0 |
current 多主题、active spec、历史 archive 的整体迁移 |
GS-04 |
docs/archive/2026-08/2026-08-19-document-governance-spec.md:10-18,43-74,75-108,121-148 |
三态、主题职责、只有 spec 不建空 plan、完整迁移和验收 |
GS-05 |
f89c1ae, 2537486 |
私有独立仓库边界、公开 archive 收敛私有运维细节 |
GS-06 |
41bfda2 |
月份 archive、事实/决定对齐 |
GS-07 |
4c64ca2 |
current-only 300、条件式 spec/plan、目录作用域澄清 |
frontend-observability-server仓库：/Users/runhaozhang/Documents/project/frontend-observability-server
| ID | 提交/文件 | 证明内容 |
|---|---|---|
GF-01 |
docs/archive/2026-08/2026-08-11-document-governance-transition-spec.md:3-14,40-170 |
原始冲突、多目录、三维元数据、状态头 |
GF-02 |
c6327e8, 0a29f60, 9439881, fcea58e, c43e56d |
复杂治理分阶段实际建立 |
GF-03 |
docs/archive/2026-08/2026-08-13-simplify-document-structure-spec.md:3-12,14-93 |
删除元数据、空目录和校验脚本；目录表达状态 |
GF-04 |
34e5085 |
精简提交，30 文件，69+/860- |
GF-05 |
docs/archive/2026-08/2026-08-18-simplify-current-document-content-spec.md:3-59,110-205 |
1,464 行 current、方案比较、事实源重构、删除预设计、写作规则 |
GF-06 |
15eaaa4, 2877060, 84a2427 |
三份 current 技术正文的实际大幅压缩 |
GF-07 |
docs/archive/2026-08/2026-08-18-use-stable-current-document-names-spec.md:3-37；1ebd1b8 |
current 稳定无日期名称；历史材料保留日期 |
GF-08 |
docs/archive/2026-08/2026-08-19-document-governance-alignment.md:3-36；5d87879 |
从二态/工具目录对齐到统一三态和跨仓库边界 |
GF-09 |
docs/archive/2026-08/2026-08-19-document-governance-v1-5-spec.md:5-19,35-63,76-100；9dee37a |
按月归档、事实/决定分流、实现差距和验证 |
GF-10 |
5946095 |
用户确认决定和条件式 spec/plan 进入项目 |
GF-11 |
9301ca7 |
current-only 300 和 spec/plan 内容边界进入项目 |
如果只用一句话概括，这套方案不是“把文档分到三个文件夹”，而是：
用最少的生命周期语义，把当前结论、活动变更和已结束上下文分开；让代码/验证、current、archive 和 Git 各自只承担自己擅长的职责，并用真实问题而不是假想流程决定何时增加规则。
它最终形成的关键取舍是：
以下为用户提供的最终文件快照全文。为了精确对应，本附录保留原始标题、版本标识、章节顺序和措辞；其 SHA-256 见文首。
本规范用于建立一套简单、清晰、可迁移的项目文档体系，使项目参与者能够快速回答：
文档体系不代替代码、测试或 Git 历史。它负责提炼结论、提供入口，并保存值得查阅的上下文。
文档只分为三种语义：
current = 当前仍然有效的事实和决定
changes = 正在讨论、准备或执行的变更
archive = 已经结束的过程、材料和历史记录
Git 负责保存文件的逐版本变化，不在 archive 中复制每一次历史版本。
除非条款明确说明适用于多个目录，针对 current、changes 或 archive 中某一目录的内容、长度或维护要求，不得类推到其他目录。
current、changes、archive 描述文档生命周期，不表示可见性。
项目资料分布在多个仓库时：
.env 实际值；<project>/current、<project>/changes 和 <project>/archive，实际路径写入 README 和 AGENTS.md。AGENTS.md
docs/
├── README.md
├── current/
│ ├── <stable-topic>.md
│ └── ...
├── changes/
│ ├── YYYY-MM-DD-topic-spec.md
│ └── YYYY-MM-DD-topic-plan.md
└── archive/
├── YYYY-MM/
│ ├── YYYY-MM-DD-topic-spec.md
│ ├── YYYY-MM-DD-topic-plan.md
│ └── YYYY-MM-DD-topic.md
└── ...
changes 使用扁平目录。archive 只按 YYYY-MM 月份建立一层目录，不再按 topic 或记录类型建立更深层目录；月份目录仅在需要归档文件时创建。
current 不规定文档数量、固定主题或统一命名清单。项目只为确实需要独立维护的当前主题创建文档，不为满足模板创建空文件。
AGENTS.md 是 Agent 的工作入口，记录：
AGENTS.md 不承担完整项目说明或历史记录的职责。
docs/README.md 是面向人和 Agent 的文档入口，内容应保持简短，包括：
current 是读取项目现状的首要入口，必须简洁、清晰、有效，并适合人类阅读。
允许记录：
不得记录：
current 中记录的事实和决定必须清晰、准确、可靠，并且明确区分。尚未实现的决定不得被写成已经实现的能力；如果决定已经生效而实现尚未符合，current 应同时明确记录有效决定和实现差距，不能把实现现状当成对决定的自动推翻。详细设计和执行计划仍应保留在 changes。
用户在任务中明确确认的决定视为已经作出；Agent 不得将提议、推测或未确认方案写成有效决定。
current 不预设文档数量、名称、组织职能或工程领域。文档可以覆盖一个主题，也可以覆盖若干紧密相关的主题；边界以能否形成完整、可独立维护的当前结论为准。
定义一份 current 文档时，应先明确：
文档边界按以下原则确定：
changes 保存尚未结束的变更材料。本规范规定变更材料的存放和归档方式，不规定哪些变更必须生成 spec、plan 或其他文件；如果任务过程中生成了这些文件，在 Change 结束前应保存在 changes。
这些材料包括：
同一个 Change 如果生成了 spec 和 plan，两者使用相同的日期与 topic：
YYYY-MM-DD-topic-spec.md
YYYY-MM-DD-topic-plan.md
spec 说明要改变什么、为什么改变、范围和验收标准。plan 说明如何实施和验证。
spec、plan 以及 changes 或 archive 中的其他材料不受 current 文档的 300 行限制。spec 和 plan 应以内容完整、无歧义并足以支持实施和验证为准；是否拆分依据变更范围和内容边界，不依据行数。
Change 完成或取消后，changes 中不继续保留对应文件；文件应移动到与文件名日期对应的 archive/YYYY-MM 目录。
archive 是按月份组织的历史资料目录，可以保存：
archive 不限制记录类型。每个文件放入与文件名日期前七位一致的 YYYY-MM 月份目录；月份目录按需创建，不再按 changes、decisions、incidents、topic 等建立更深层目录。
归档内容不是当前事实来源。仍然有效的结论必须提炼到 current；archive 只负责保存形成结论的过程和上下文。
统一使用：
YYYY-MM-DD-topic.md
YYYY-MM-DD-topic-spec.md
YYYY-MM-DD-topic-plan.md
规则如下：
提出变更
→ 如任务产生 spec、plan 等变更材料，将其保存到 changes
→ 修改与验证
→ 将最终事实和有效决定提炼进 current
→ 将已有变更材料移入 archive/YYYY-MM
归档前必须先更新 current，避免历史材料已经移走而当前事实仍然缺失。
如果 Change 被取消：
讨论或调查结束后：
实现事实与有效决定使用不同的可信度规则，不使用同一条顺序处理。
判断当前实现、构建、发布或外部状态时，按以下顺序取证：
当前代码、测试、构建和当次外部验证
> docs/current 中对实现事实的描述
> docs/changes
> docs/archive
> 未经重新核验的旧描述
判断已经生效的决定、契约或政策时，以 docs/current 中明确记录且当前仍然有效的对应内容为规范来源。代码、测试和构建只能证明当前实现，不自动推翻有效决定。
如果当前实现与有效决定冲突，该冲突本身就是需要展示的当前事实。核验冲突后，应在 current 中同时保留有效决定并明确标注实现差距；相关修复设计和计划保留在 changes，完成后再更新 current。
维护要求：
current 中的每份文档都应适合人类阅读，并满足：
判断一段内容是否属于 current 时，使用以下问题：
删除这段历史过程后，读者是否仍能准确理解项目现在是什么、为什么必须这样做？
如果答案是“能”，该过程不应留在 current。
首次采用本规范时：
迁移时优先移动和提炼，不为了“干净”而删除仍有历史价值的资料。
开始任务前：
完成重要功能或 Bug 修复后：
纯格式、注释等不改变项目状态的修改，不要求更新 current。
可将下面内容复制到其他项目的 AGENTS.md，并按项目需要补充：
## 文档治理
- 将 `docs/current` 作为当前项目事实和有效决定的简洁来源。
- 保持 current 文档简洁并适合人类阅读；事实和决定必须清晰、准确、可靠并且明确区分。
- 仅对单份 current 文档设置 300 行上限；超过 300 行时，应根据 current 文档边界原则考虑如何合理拆分，不得通过合并长段落规避限制。该限制不得用于 changes 或 archive 中的 spec、plan 及其他材料。
- current 文件名应简短清晰，使用常见、易懂的单词，不使用日期、复杂单词、冗长组合或不必要的缩写。
- 将未结束变更的 spec 和 plan 以扁平文件形式保存在 `docs/changes`，命名如下：
- YYYY-MM-DD-topic-spec.md
- YYYY-MM-DD-topic-plan.md
- 变更实施并验证后，先更新受影响的 `docs/current` 文件，再将其 spec 和 plan 移入与文件名日期对应的 `docs/archive/YYYY-MM` 目录。
- 将已完成的讨论、调查、根本原因、历史验证、被替代文档及其他已结束记录，保存为对应 `docs/archive/YYYY-MM` 月份目录中的带日期文件。
- archive 月份目录应与其中每个文件名的日期前七位一致，并且仅在需要时创建；不要按 topic 或记录类型建立更深层目录。
- 每项当前事实只在一个仓库中保留权威来源；其他仓库仅保留摘要或链接。
- 不要将私有基础设施值复制到公开文档中。
- 不得在文档中保存密码、私钥、Token、AccessKey、数据库凭据或 `.env` 实际值。
- 判断实现事实时，以当前代码、测试、构建和当次验证为准。
- 将 `docs/current` 中记录的有效决定、契约和政策作为规范性来源。
- 实现与有效决定冲突时，将冲突视为缺陷，并明确记录该决定和实现差距。
- 除非在当前任务中完成验证，否则不得将变化中的外部状态表述为当前状态；应标注最后验证日期或标记为未验证。
current 负责清楚地说明现在。
changes 负责推动下一次改变。
archive 负责保存已经结束的过程。
Git 负责保存每个文件如何变化。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。