背景

設計の理由

AI エージェントの支援による翻訳です。内容に相違がある場合は、英語版ページが優先されます。文章に問題を見つけた際は、Issueまたはプルリクエストをお願いします。

この文書は規範的ではありません。仕様がこの形になった理由を説明します。

指示ではなく意図を#

命令形の指示（「これを、この形式で、このベンダーファイルに対して実行する」）は、エージェントホストやタスクが変わるたび、新しいメンバーが加わるたびに書き直す必要があります。一方、持続する意図（何を意味し、何が成立していなければならず、なぜそうなのか）は、一度記述すれば、どのホストやタスクでもそこから必要な行動を導き出せます。

そのため、コンテキストレイヤーのカテゴリには、タスクではなく持続的な意味に基づく主題の軸（ドメイン、システム、ガバナンス、決定）を採用しています。将来のバージョンでは、実際の運用に基づくタスクエンベロープが加わる可能性があります。1.0 では、意図的に小さなサーフェスだけを標準化しています。

階層ではなく輪#

現在、コンテキストに関する文書の多くは、エージェント向けに書かれています。人が指示を書き、エージェントホストがそれを読み込むという、一方向の階層構造です。これによって個々の作業は速くなりますが、以前からある問題は解決されません。人から人へ伝えるべき知識は頭の中やスレッドに残り、エージェントホストごとに、少しずつ実態とずれていく情報の写しを抱えることになります。

Leji は、ひとつのコンテキストレイヤーを囲む 3 つの流れを等しく一級のものとして扱います。人から人へ（オンボーディング、レビュー、議論の決着）、人から AI へ（エージェントに委ねる作業）、そして人から AI を経て人へ（エージェントが作ったものを人がレビューする）です。

全員が同じコンテキストレイヤーを読み、人もエージェントも変更を提案します。アクセスは平等でも、権限は平等ではありません。書き込みはすべて提案として行われ、何を真とするかは人が承認します。3 つの流れすべてに役立つ内容であること自体が、更新を促す力になります。エージェントしか読まないページは気づかれないまま劣化しますが、人も頼りにするページなら、どちらの側からも修正されます。

意図と記録#

実際のリポジトリにあるドキュメントには、真実の捉え方が異なる 2 種類の情報が混在しています。意図（用語集、不変条件、規約、ガードレール）は、真であり続ける必要があります。現実が変われば、文書のほうを更新します。一方、記録（ステータス、評価、台帳、報告、アーカイブ）は、一定の境界内で真のものとして作成されます。後の状態によって置き換えられ、日付によって、いつ時点の記述かが決まります。

記録を意図として扱うと、誰も守れないレビューの約束が生まれます。かといって記録を除外すれば、リポジトリの大部分がガバナンスの外に置かれます。Leji は代わりに、両方を区別したうえで統制します。

記録も意図と同じようにインデックスされ、レビューを受け、所有者を持ちます。ただし、必須のコンテキストではなく、日付付きの候補として扱われます。読み手に対する契約が異なるからです。記録は日付のある証拠であり、現在の真実ではありません。鮮度の期限が適用されるのは意図だけです。5 つのカテゴリは引き続き主題の軸であり、種別はそれと直交します。システムの評価は、システムについて記述すると同時に、その日付の時点で真だった内容でもあります。

仕様は、どの記録が「最新」かを認定しません。1.0 では、記録の系列も順序も宣言していないためです。読み手は、インデックスに記載された日付から新しさを判断します。仕様自体の決定記録は、日付を持ち、追記のみで管理され、鮮度の期限による失効の対象にはなりません。このパターンの実例でもあります。

これがウィキではない理由#

ウィキが劣化するのは、最新の状態を保つ仕組みがないからです。コンテキストレイヤーには、ウィキにはない 3 つの強制力があります。

• エージェントがタスクのたびに読むため、誤ったコンテキストは、その日のうちに誰かが問題を実感するような誤出力を生みます。
• 変更はコードレビューに含まれるため、別プロセスとして忘れ去られることがありません。
• 機械的なずれ（古いインデックス、壊れたプロファイル）はチェックの失敗として検出されます。governed では、そのチェックが変更のたびに CI で実行されます。追記のみのチェックは、作業ツリーの変更履歴を HEAD のものと比較します。そのため、作業ツリーに残っている巻き戻しはこのチェックで失敗しますが、すでにコミットされた状態で持ち込まれた巻き戻しを捉えるのは、このチェックではなく変更セットのレビューです。

ベンダーファイルが誘導にとどまる理由#

正典となるコンテキストを特定ベンダーの設定形式に置くと、情報が分断され、そのホストに縛られます。エージェントホストはそれぞれのエントリポイントを探すため、Leji はそのファイルをアダプタとして使います。内容はブートプロファイルを指す 1 行だけです。ひとつの出典なら、どのホストよりも長く存続します。

フェデレーションが中央集約ではなく合成である理由#

すべてのチームの知識を中央に集約すると、コンテキストを最新に保つ所有のループが崩れます。所有者は、タスクのたびに利用しながら自分たちのレイヤーを修正します。中央リポジトリでは内容と説明責任が切り離され、チームをまたぐ編集は門番の承認待ちになります。

フェデレーションなら、所有と参照のしやすさを両立できます。各チームのコンテキストレイヤーはそれぞれのリポジトリに残り、そのチームの輪の中で読まれ、承認されます。ホスト側は、閲覧とエージェントの誘導のために、ピン留めしたバージョンの兄弟レイヤーをマウントします。内容がホストへコピーされたり、コミットされたりすることはありません。

変更を承認するのは、引き続き兄弟レイヤーの所有者です。マウントによって得られるのは読み取りアクセスであり、権限ではありません。ほとんどのチームに federated は必要ありません。これが有効なのは、独立性を保つ価値のあるコンテキストレイヤーを、すでに 2 つ以上のチームが所有している場合だけです。

一人のチーム#

この輪のどの部分にも、複数の人は必要ありません。同じ一人が提案し、エージェントに作業を委ね、承認できます。その場合でも、エージェントはレビューと助言を担う側であり、所有して承認するのは人です。マニフェストの agents マップによって説明責任が移ることはありません。

一人のチームは最小の輪であり、別の形ではありません。このモデルは、一人からひとつのチーム、複数チームで構成される組織へと、要素を追加せずに拡張できます。