黑匣子 (blackbox)
概述
黑匣子是一个项目的飞行记录器：针对每个经所有者批准的变更单元，记录一次非摘要化的决策记录——包括所有者的实际原话（逐字记录）、在上下文中的含义、助手推荐和构建的内容、原因、驱动每个选择的证据，以及助手在此过程中犯下的错误——这些记录被固定在所解释的内容上，且仅在需要时按需读取。它的存在是为了让未来的会话能够审计某个规则的来源，而不是重新争论它。
它不是什么（两件事）：
- 不是对话记录。 选择并非摘要。入口是从决策轨迹（而非聊天日志）编写的：那些帮助所有者理解但未改变决策的教学、类比和绕路都被省略。保留的内容则以完整形式保留。
- 不是关于所有者的日记。 它记录的是说了什么和决定了什么，而不是所有者是谁。工作风格方面的观察应记录在助手的记忆中，绝不在此处。
该项目是否有黑匣子？
- 项目旁边（或仓库根目录）存在
blackbox/README.md→ 该约定适用。在撰写你自己的入口之前，请先阅读该 README 以及最新的入口——入口架构来源于它们，绝不能来自你自己的想象。 - 没有标记，且所有者要求采用 → 引导操作：将此技能目录中的
blackbox/README.md复制到项目中，仅更改项目名称，然后将此次采用本身记录为第一个入口。 - 没有标记，且你即将在此会话中首次编辑某个规范/约定/设计文档 → 检查标记。如果缺失，用一句话提供一次采用建议，然后继续执行所有者的任务。采用由所有者决定；如果他们拒绝，请在记忆中注明，这样该仓库就不会再次被询问。
采用的单元是包含标记的目录——可以是某个技能、包或整个仓库。任何仓库、任何合并方式均可。
单元和时机
- 每个经所有者批准的单元一个入口：已确认的规范、已合并的 PR、已修订的约定。不是每提交一次就记录，也不是每轮对话就记录。一个产生多次提交的单元只需一个入口。
- 在决策发生的会话中撰写。 原始交流仅存在于当前上下文中；会话结束后，只有摘要存活，逐字引用将消失。如果一个单元耗时较长或跨越多个会话，尽早保存草稿——填写
Refs: pending、所有者引用和索引部分——并在批准时最终确定（固定 blob 引用，完成正文）。草稿优于事后重构的记忆。
操作方法（每个经所有者批准的单元）
- 进行修改。
- 按内容固定结果。 对于每个更改的文件，在工作树上执行
git hash-object <路径>。Blob SHA 是基于内容的寻址——相同的字节永远散列出相同值，因此固定操作可经受压平合并、变基和任何历史重写，并且在任何提交之前就已存在。 - 以如下格式编写入口
blackbox/YYYY-MM-DD-<slug>.md：包含索引（指向正文）以及原始正文。 - 将入口与更改一同提交——同一提交或同一 PR，按照仓库通常的合并方式合并。
验证固定：git hash-object <路径> 并比较。检索固定状态：git log --find-object=<sha> 或 GitHub Blobs API。
阅读规则：在对项目进行正常工作期间，永远不要加载 blackbox/。只有在需要追溯来源问题时才读取它。
入口格式
# YYYY-MM-DD — <标题>
Refs: <路径> @ blob <sha> （每个更改的文件一行）
Decisions: <决策> <权重> [→ <新权重>, 见 §…] · …
Reversals: §… · §… （或: 无）
Owner caught: §… · … （或: 无）
Declined: §… · … （或: 无）
Evidence: <命令/数字/链接> · …
Understanding: §… （或: 不适用）
---
<原始正文，包含索引指向的 § 标题>
索引行指向正文；它们从不替代正文。
- Decisions — 该单元包含的每个决策，以及助手在询问时分配的权重（🔴 必须立即决定 · 🟡 决定，可修订 · 🟢 采纳推荐）。如果后来权重被更改，请说明并指向原因。随着时间的推移，这一行是所有者审计自己是否对决策给予了应有的重视的依据。
- Reversals — 助手曾断言但后来撤回或纠正的任何内容：错误的声明、被测量结果推翻的推荐、未经询问做出的决定。
无是一个有效值，且必须显式写出。 - Owner caught — 所有者发现的不一致或缺陷（错误的计数、遗漏的项目、结构性错误）。所有者的审计，不仅仅是助手的审计。
- Declined — 有意未采纳的选项、工具默认值或外部推荐，并在正文中说明原因。
- Evidence — 决策时实际查看的内容：运行的命令、产生的数字、显示的页面或文件。记录可复现的步骤，而非截图——图表从其命令重新生成；截图则不是。
- Understanding — 如果所有者在批准时表示他们并未完全理解，则记录他们的陈述以及日后需要重新解释的内容。
语言
- 正文：英语，无论仓库的文档语言是什么。
- 所有者的输入：原始逐字引用，然后是英文转写。 首先以
>块引用形式提供逐字引用，完全按照输入时的原样——包括拼写错误、缩写、ㅇ等。然后是转写：内容完整、形式自然、自成一体（没有其他上下文的读者也能理解它）。逐字引用是证据——只有在那里才能发现改变决策的拼写错误。转写是助手当时的理解——如果两者不一致，入口已经记录了问题。 - 助手的回复、理由和内部处理：使用英语，对于任何影响决策的内容，以完整形式呈现。
> ㅇ后跟所有者批准了选项（a）。是一个完整的记录；不必填充额外内容。
硬性规则
| 规则 | 不要这样做 |
|---|---|
| 所有者输入 = 逐字引用 和 英文转写 | 仅有逐字引用（无上下文不可读）、仅有转写（证据丢失）或一行摘要 |
索引在顶部，原始正文在下方，索引行指向 § 标题 | 代替指向的摘要性索引；没有索引的正文；填充一行内容的章节 |
| 正文来源于决策轨迹 | 未改变任何决策的教学、类比或绕路 |
Reversals: 必须出现，即使为 无 | 仅列出正确内容的入口 |
Refs: = 每个文件的 blob SHA（git hash-object） | 使用提交号或 PR 号作为锚点——历史重写会使其失效 |
| 入口与更改在同一提交或同一 PR 中 | 稍后“另一个” PR |
| 在决策发生的会话中撰写 | 下一会话凭记忆重构 |
| 入口架构来自 README 和最新入口 | 自创格式 |
危险信号
- 没有
Refs:行的入口，或Refs:使用提交号或 PR 号而非 blob 引用 - 没有
>逐字引用的所有者输入，或者引用后没有转写 - 完全没有
Reversals:行 - 摘要性而非指向性的索引行
- 向读者解释概念而非记录决策内容的正文
- 未附带入口就合并的更改
- 在记录决策之后的会话中编写的入口（如果无法避免，请在入口中说明）
来源说明
blackbox/ 保存了此项目的完整决策记录——所有者输入（逐字引用 + 英文转写）、助手推理、证据和撤回内容，按每个批准的变更以内容寻址方式固定。仅在调查某个规则为何存在或所有者最初要求什么时读取它。正常使用期间绝不加载。