context-infra 检查与复盘infra.guiming.net · 全内容自包含呈现 · 生成于 2026-07-21 16:28 UTC

workflow_file_storage_and_requirement_protocol

Z3 全文↑ Z2 条目

道-方法 · 道层 skill 全文

← 返回道层 skill 索引 · 返回方法论区

本页是 <code>rules/skills/drafts/workflow_file_storage_and_requirement_protocol.md</code> 的逐字投影（仅隐私清洗，零改写）。

时点提示：本页是仓内文件 rules/skills/drafts/workflow_file_storage_and_requirement_protocol.md 的逐字投影（仅做隐私清洗：仓库根绝对路径→相对路径、家目录→~/；除此零改写）。若源文件后续有修订，以仓内真源为准。

报告元数据（frontmatter）
name: workflow_file_storage_and_requirement_protocol
status: draft (Beta) — 2026-06-13 起草（PR-4，session 0468dca9）；2026-06-17 对齐 fa-3（schema 真源 = DESIGN_FA_ARCHITECTURE_SSOT.md；本 skill 是道导航/方法，不再平行重述 schema 细节，schema 看 fa SSOT）；晋级前需 ≥3 个真实 program 按本 SOP 建/重组并过 fa_structure_gate，且 DDP 多文件需求记录在 ≥2 program 上跑通
tier: 道（治理）
description: 一个 adhoc program（job）内部「文件放哪 / 需求怎么记 / 报告锚什么」的统一 SOP。指导后续所有文件的存放与需求记录：fa-3 存放架构（根四件套 + 真源/运行二分 + 单一真源指针 + 溯源四键 + 任务分层 audits//reorgs/ + 缓冲 _buffer/ + 过时化）+ DDP 优化的需求记录协议（设计/执行两级分离 + 按领域多文件 + 忠于原文 + 时间轴 + 角色化写入）+ 报告锚设计需求。触发场景：在 adhoc program 内新建/放置任何文件、记录用户需求、写实现/收口报告、或重组一个旧 program。配套确定层工具 fa_structure_gate + requirement_doc scaffold。

文件存放与需求记录 SOP（道·治理）

这是 program 内部的存放与需求记录统一规范，指导后续所有文件。它把 r001 的 fa-1 存放架构 + r002 的 DDP 优化（需求记录协议）合成一份可机械验证的治理。WORKSPACE「文件存放架构」节决定「文件放进哪个 job」（job 间），本 SOP 决定 job 内部怎么组织。理论依据见 WORKSPACE 节同款（Glushko/Pirolli/Ousterhout/Simon/Brooks/Weinberg）+ DDP v0.4 角色协议。

一句话

一个 program 内部，真源与运行产物二分、设计需求与执行需求文件级分离、需求按领域多文件逐字记录且自带时间轴、报告锚设计需求、副本只放指针不复制——这五条对人和机器都可读、可机械校验（fa_structure_gate + requirement_doc），新 session 零先验即可遵循。

何时用

放任何文件、记任何用户需求、写任何实现/收口报告、重组任何旧 program 前，先过本 SOP。trivial 单文件查询不必。

Part 1 — 文件存放（fa-3 架构）

根四件套（每个 program 必备，固定名）：

固定槽位（按需建，固定名）：

三条贯穿纪律：

Part 2 — 需求记录（DDP 优化协议）

DDP 的首要产物是需求记录（不是设计细节）。采纳 design_doc_protocol_loop_codex_20260501/protocol_versions/v0.4/ 的角色化多文件协议，按下面重定心：

(a) 设计需求 vs 执行需求两级文件级分离：设计需求（「模块应做成什么样」）进 REQUIREMENTS_DESIGN/requirements/design/；执行需求（「这轮怎么跑」）进 EXECUTION_REQUIREMENTS。节内分节挡不住夹杂，必须文件级分离。

(b) 设计需求按领域多文件：program 跨多模块时，REQUIREMENTS_DESIGN.md = 索引（域→文件→版本→一句话，GENERATED 块），requirements/design/<域>.md = 每域一文件权威源（对齐 v0.4 INDEX + detail docs / CONTENT-ROUTING）。一个领域一个文件，不同领域内容分开存。

(c) 忠于原文逐字：需求原文逐字保留，不转述、不蒸馏、不把「你对我的要求/方法论」改写进去。逐条挂 provenance（session id + raw turn 锚）。独立分析（agent 的实现建议/说明）与需求原文分文件/分区记录，标哪个 agent 哪个 session（DD-04）。机械保障 = 复用现成 requirement_doc 原语：R1 原文区 sha256 冻结（改一字 FLAG）+ R2 说明必须锚 R1 引文 ID 不得改写 + R3 分析强标 agent+session，配 check_requirement_doc（RD1-RD4）。这套已存在（不另造），多文件域记录理想形态 = 每域文件 R1 冻结。

(d) 时间轴强制：每个需求文件带 CHANGELOG（| 版本 | 日期 | session | 变更 |）+ 版本号（设计版本采 v0.4 D<major>.<minor>.<patch>，语义=需求变了多少：Major 推翻需求/删组件、Minor 新增需求内容、Patch 修正）。prompt 里出现新设计关注点，及时回写对应域文件 + CHANGELOG 加一行。

(e) 设计细节可选：需求文件只放需求 + 时间轴，可不记设计细节（设计/需求解耦）。真要做设计时，设计细节进 design/ 的设计文档（另一产物，走 design_doc 三层 + check_completeness）。

(f) 角色化写入（协议层采纳，运行时按需）：写需求记录时分离角色——Designer 从原文抽取、Decomposer 按领域路由到文件、Writer 逐字写入、Reviewer 验忠实度。渐进式披露：每角色只读自己需要的。多文件/跨 session 时用独立 sub-agent 承担 Writer（注入完整背景 + 严格逐字纪律），主 agent 验。

Part 3 — 报告锚定（FA-9）

实现/收口/走查类报告，需求锚 = 被实现对象的设计需求真源（REQUIREMENTS_DESIGN 及其域文件），逐条对照实现情况。报告 session 自身的局部诉求只约束报告形式，不得成为报告主轴。报告 frontmatter requirement_anchor 指设计需求文件路径，使锚定层级可机械检查（fa_structure_gate FG3）。

（反例标本：infra_production_push_20260611/reports/ 锚了报告 session 的 RQ-1~6 局部诉求当主轴，设计需求对照退成一个子报告——这是两级未分离 + 报告锚错层级的产物，本 SOP 三条合起来防它复发。）

Part 4 — 迁移与弃用纪律

4.1 新内容

新内容一律按 fa-3 + 本 SOP 存放。

4.2 旧内容弃用：区分「归档」与「过时化」两种操作

旧内容有两种正确处理，按它是「该从活跃区挪走」还是「被新版取代但留原处作历史」选其一。两者都不用纯指针桩冒充已处理。

(A) 归档（physical archive） — 内容完成、过时或冗余，该从活跃区挪走：物理移动到 archive/（常规）或 redundant_archive/（冗余），走 rules/ARCHIVE_SOP.md 台账。归档区必须是真实文件，绝不是指针/链接/「见某某」占位（纯指针桩违反 ARCHIVE_SOP §4.3）；原位置不留 redirect stub（仅当存在外部硬引用且经判定，按 ARCHIVE_SOP §9 例外保留极简指针）。借机纠正历史错放；只移动不增补内容。

(B) 过时化（obsolescence，fa-3 §2.6 / FA-22） — 一个真源被新版 supersede，旧版要留原处作历史 rationale：① frontmatter 加 status: obsolete/superseded + superseded_by: <新真源路径>；② 需名级可辨时目录加 _OBSOLETE 后缀，走 reference_validator CASCADE 更新引用，绝不裸 git mv；③ 旧内容不删，只标过时 +（必要时）改名 + 收口指针指向新真源。改名是高后果操作：引用海量时只标 frontmatter + banner、不改名（核引用量后定）。

判别：要把东西挪走 → (A) 归档；要把东西留原处但标明被取代 → (B) 过时化。

两种 archive 区分（A 的两个桶）：

4.3 物理迁移工具

物理迁移走 reference_validator rename（CASCADE 更新引用），分步过门，不裸 git mv。reference_validator 现不覆盖 adhoc_jobs（SCAN_DIRS 排除），故 adhoc 间物理搬迁前必须手工核活跃引用链（TODO/CRONTAB/test/cron），或先把 adhoc_jobs 纳入 reference_validator 覆盖（fa-3 S2 切片）再搬。

重组用指针时，指针只合法指代三类用途——存放位置 / 旧代码位置（已过时化或已归档的历史实现）/ 新代码库位置（live 工具真源）；authored 真源物理在位。运行产物按这三类判：是历史/外部 live 则指针合法、且被指向物状态须明确（obsolete/archived/live），是当前一等内容则物理归位。绝不用指针把本该物理一等的当前内容留在旧文件夹冒充已整合（迁移捷径指针 = 反模式）。

验收（机械可查）

边界 / claim ceiling

证据 observational+bounded：本 SOP 是 r001（fa-1）+ r002（DDP 优化）两个真实 program 采用的综合，fa_structure_gate 在 2 个 program 上 PASS、DDP 多文件需求记录在 PP reorg 上 demo 一次。未经 ≥3 program 长期采用验证；角色化写入协议层采纳、全角色运行时工具化（v0.4 七角色端到端）列 deferred 演进。本 SOP 是道（怎么组织 + 为什么），具体工具路径查 tools/INDEX.md，工具替换后道仍成立。

SSOT + 模块化接缝

本 SOP 的 fa-3 存放架构（Part 1）是文件存放 SSOT，与代码/设计模块化判断是正交的两件事：

配套与跨域

← 返回道层 skill 索引 · 返回方法论区