blackbox
概要
ブラックボックス（blackbox）は、アイテムの飛行記録です。所有者が承認した変更単位ごとに、1つの要約されていない決定記録が存在します。それには、所有者が実際に言ったこと（逐語）、それが文脈で意味したこと、アシスタントが推奨し構築したもの、その理由、各選択を導いた証拠、そしてアシスタントが途中で誤った点が含まれます。これは説明するコンテンツに紐付けられ、オンデマンドでのみ読み取られます。将来のセッションがルールの起源を監査し、再議論する必要をなくすために存在します。
ブラックボックスがではないもの：
- トランスクリプトではない。 選択することは要約することではありません。エントリは決定の過程から書かれ、チャットログからではありません。つまり、教育、類推、および所有者が理解するのに役立ったが決定を変えなかった脱線は除外されます。保持されたものは完全な形で保持されます。
- 所有者についての日記ではない。 言われたことと決定されたことを記録し、所有者が誰であるかは記録しません。作業スタイルに関する観察はアシスタントのメモリに属し、ここには決して置かれません。
このアイテムにはブラックボックスがありますか？
blackbox/README.mdがアイテムの隣（またはリポジトリルート）にある場合 → この規則が適用されます。そのREADMEと最新のエントリを両方読んでから、あなたのエントリを書いてください。スキーマはそれらから来ており、あなたの頭から決して来ません。- マーカーがなく、所有者が採用を依頼した場合 → ブートストラップ：このスキルのディレクトリから
blackbox/README.mdをアイテムにコピーし、アイテム名以外は変更せず、採用自体を最初のエントリとして記録します。 - マーカーがなく、このセッションで初めて仕様/規約/設計文書を編集しようとしている場合 → マーカーを確認します。ない場合は、一度だけ採用を提案し、一文で行い、その後所有者のタスクを続行します。採用は所有者の判断です。断られた場合は、リポジトリに再度尋ねないようにメモリに記録します。
採用の単位は、マーカーを含むディレクトリ（スキル、パッケージ、またはリポジトリ全体）です。任意のリポジトリ、任意のマージ方法で機能します。
単位とタイミング
- 所有者が承認した単位ごとに1エントリ：確認された仕様、マージされたPR、改訂された規約。コミットごとではなく、会話のターンごとでもありません。複数のコミットを生成した単位は1つのエントリを取得します。
- 決定が行われたセッションで書かれます。 生のやり取りは現在のコンテキストにのみ存在します。セッションが終了すると、要約のみが残り、逐語引用は失われます。ユニットが長引いたり、セッションをまたぐ場合は、早期に下書きを保存します（
Refs: pending、所有者の引用、インデックスを記入し、承認時に最終化（ブロブを固定、本文を完了）します）。下書きは再構築された記憶より優れています。
レシピ（所有者承認ユニットごと）
- 変更を行います。
- 結果をコンテンツで固定します。 変更された各ファイルについて、ワーキングツリーで
git hash-object <path>を実行します。ブロブSHAはコンテンツアドレス指定されます。同じバイトは常に同じハッシュになるため、固定はsquash、rebase、および履歴書き換え後も存続し、コミットの前から存在します。 - 下記の形式でエントリ
blackbox/YYYY-MM-DD-<slug>.mdを書きます。 本文を指すインデックス、次に生の本文。 - エントリを変更とともにランドさせます — 同じコミットまたは同じPRで、リポジトリが通常マージする方法でマージします。
固定の確認：git hash-object <path> を実行して比較します。固定状態の取得：git log --find-object=<sha> またはGitHubブロブAPIを使用します。
読み取りルール：アイテムの通常作業中は blackbox/ をロードしないでください。出典に関する質問がある場合にのみ読み取ります。
エントリの形状
# YYYY-MM-DD — <title>
Refs: <path> @ blob <sha> (変更されたファイルごとに1行)
Decisions: <decision> <weight> [→ <new weight>, see §…] · …
Reversals: §… · §… (または: none)
Owner caught: §… · … (または: none)
Declined: §… · … (または: none)
Evidence: <command / number / link> · …
Understanding: §… (または: n/a)
---
<生の本文、インデックスが§見出しを指す>
インデックス行は本文を指します。決して本文を置き換えません。
- Decisions — ユニットに含まれるすべての決定、アシスタントが尋ねた際に割り当てた重み付き（🔴 今すぐ決定必須 · 🟡 決定、修正可能 · 🟢 推奨を受け入れる）。重みが後で変更された場合は、その旨と理由を明記します。時間とともに、この行は所有者が自分たちの熟考を決定にふさわしい重みに対して監査する方法となります。
- Reversals — アシスタントが主張し、後に撤回または修正したものすべて：誤った主張、測定によって覆された推奨、尋ねずに行った決定。
noneは有効な値であり、明示的に記述する必要があります。 - Owner caught — 所有者が発見した不整合や欠陥（誤った数、欠落アイテム、構造上のバグ）。アシスタントだけでなく、所有者による監査。
- Declined — 意図的に採用しなかったオプション、ツールのデフォルト、または外部からの推奨。理由は本文に記載。
- Evidence — 決定時に実際に参照されたもの：実行したコマンド、それが生成した数値、表示されたページやファイル。再現を記録し、画像ではない（図はコマンドから再生成される。スクリーンショットは再現ではない）。
- Understanding — 所有者が完全には理解していないと述べながら承認した場合、その発言と後で再説明する必要がある内容。
言語
- 本文：英語。リポジトリの文書言語に関係なく。
- 所有者の入力：元の逐語、次に英語のリライト。 最初に逐語を
>引用で、正確に入力されたまま（タイプミス、略語、ㅇなどすべてを含む）。次にリライト：内容は完全で、形式は自然で、自己完結型（他のコンテキストがなくても読者が理解できる）。逐語は証拠です。決定を変えたタイプミスはそこでしか見つかりません。リライトは当時のアシスタントの解釈です。両者が一致しない場合、エントリはすでにその欠陥を記録しています。 - アシスタントの応答、論拠、内部処理：英語。決定に関わるものは完全な形で記述します。
> ㅇの後にOwner approved option (a).と続けるのは完全な記録であり、水増しは不要です。
厳格な形式
| ルール | こんなのダメ |
|---|---|
| 所有者の入力 = 逐語引用 および 英語リライト | 逐語のみ（コンテキストなしで読めない）、リライトのみ（証拠が失われる）、または一行の要約 |
インデックスは上部に、生の本文は下部に、インデックス行は § 見出しを指す | 要約する代わりに指すインデックス、インデックスのない本文、一文で埋められたセクション |
| 本文は決定の過程から取られる | 決定を変えなかった教育、類推、脱線 |
Reversals: が存在する、たとえ none でも | うまくいったことだけを列挙するエントリ |
Refs: = ファイルごとのブロブSHA（git hash-object） | コミット番号やPR番号をアンカーにする（履歴書き換えでそれらは消える） |
| エントリは変更と同じコミットまたはPRでランドする | 「後で」フォローアップPR |
| セッションで決定が行われたときに書く | 次のセッションで記憶から再構築 |
| READMEと最新エントリからエントリスキーマを取得 | 考案されたフォーマット |
危険信号
Refs:行がないエントリ、またはコミットやPRをブロブの代わりに指定したRefs:>逐語引用のない所有者入力、または引用の後にリライトがないものReversals:行がまったくない- 要約ではなくポインタとして機能するインデックス行
- 読者に概念を説明する本文で、何が決定されたかを記録していない
- エントリなしでマージされた変更
- 記録する決定が行われた後のセッションで書かれたエントリ（やむを得ない場合はエントリ内にその旨を明記）
出典
blackbox/ は、このアイテムの完全な決定記録を保持します。所有者の入力（逐語 + 英語リライト）、アシスタントの推論、証拠、および覆しを含み、承認された変更ごとにコンテンツ固定されています。ルールが存在する理由や所有者が当初何を求めたかを調査する場合にのみ読み取ってください。通常の使用中にロードしないでください。