knowledge-layers

ナレッジの階層

AGENTS.md または .context/ ファイルを作成・編集するときは、/creative-writing-skills:qi-layer を読み込んでください。作成の指針（4つの原則、内容のガイドライン、含めるべきでないもの）を扱います。 開示レベルについては、まだ読み込んでいない場合、/creative-writing-skills:information-hierarchy を読み込んでください。 まだ読み込んでいない場合、/creative-writing-skills:llm-writing を読み込んでください。

5つの階層

階層	格納する内容	使用する場面
AGENTS.md	ディレクトリの意図とメンタルモデル	エージェントがディレクトリに入ったとき最初に読むもの。ここで作業する前に理解しておくべきこと
.context/	契約、アーキテクチャ、根拠（CONTEXT.md）；先送りされた作業（TODO、FUTURE）	参照用の詳細情報と追跡対象の先送り事項を、それらが説明する資料と同じ場所に配置
KB	横断的な決定事項、ドメインの概念、パターン	複数のディレクトリにまたがるもの。セッションを越えて有効なもの。単一のディレクトリが所有しないもの
docs/	ユーザー向けドキュメント	対象読者や更新頻度が異なるもの
作業ディレクトリ	一時的な設計上の決定と下書き	永続的な内容と同じ場所に置かず、進行中の作業項目に限定するもの

配置ルール

ディレクトリの意図やメンタルモデルなら → AGENTS.md。 エージェントが参照する、ディレクトリに限定された詳細情報なら → .context/。 このディレクトリに限定された先送り作業なら → .context/TODO（必須） または .context/FUTURE（あると望ましい）。フラットな Markdown リストにし、各項目には 影響を受けるパスと具体的なフォローアップを記載します。横断的な項目や 外部から確認できる必要がある項目は、代わりにプロジェクトの課題管理システムに登録します。 全体像、つまり横断的な決定事項、ドメインの概念、 上位レベルのシステムアーキテクチャなら → KB。 エンドユーザー向けなら → docs/。 人間がエージェントを修正する場合なら → KB の修正記録 （resources/corrections/register.md。コードプロジェクトでは、その隣に code.md）。 繰り返し発生する修正パターンは /creative-writing-skills:correct で解消します。 一時的な作業成果物なら → 作業ディレクトリ。

迷ったら、関連資料と同じ場所に置きます。特定のサブシステムに依存するナレッジは、 概念のように見えても、そのサブシステムの AGENTS.md または .context/ に置きます。 KB は特定の実装に依存せず、その実装が変更されても残るものを保持します。 説明対象から遠く離れたナレッジは、より早く陳腐化します。対象の変更時に、 離れたドキュメントも更新が必要だと気づけないためです。

KB から作業内容自体のドキュメントへリンクします。 作業に関する情報を KB に書く前に、 その作業のドキュメント、AGENTS.md、.context/、および更新されたコメントを読みます。 それらが説明する内容にリンクし、そこに書かれていないことだけを書きます。 つまり、確定した意図、その理由、却下した代替案、プロジェクトの残りの部分との関係です。 すべてが記載されている場合、KB に置くのはリンクだけにするか、何も置きません。 内容を再記述している KB のセクションは、リンクと、元の資料に書かれていない部分だけが残るように削ります。 コピーした内容は、次に元の資料が変更されたときに乖離していきます。

現在の真実を優先し、履歴は残さない

AGENTS.md、.context/、KB、docs/ など、永続的な各層には、現時点で最善の理解を記録します。作業項目が進行中の間は、作業ディレクトリに中間的な推論を残してもかまいません。永続的な内容が古くなったら、削除するか、KB ページの場合は archive/ に移動します（.kgignore によってナレッジグラフから除外されます）。現在有効な内容から、アーカイブ済みの内容を参照してはいけません。ページは常に現在の真実として読めるようにし、変遷の記録にはしません。

削除に代わりの内容は必要ありません。 対象がなくなったページや、システムに存在しなくなった挙動を説明するページは、置き換える内容がなくても、見つけ次第削除します。古い知識は空白よりも有害です。エージェントがそれを読み込み、そこから推論してしまうためです。削除するかどうかは、内容の真実性に責任を持つ担当者が判断します。構造上の役割を持つ担当者は、問題を指摘するにとどめます。

履歴はアーカイブに残します。 バージョン管理されたツリーでは、未追跡ファイルを削除する前にコミットし、削除を履歴に残します。また、コミットメッセージに何を削除したか、その理由を記載します。それ以外の場合は、削除する前に、今後も必要な情報をプロジェクトのアーカイブに保存します。保存したものが本当に失われることはないため、削除は簡単に行えます。

各層の真実は、その層を基準にします。 AGENTS.md と .context/ は、それらを含むツリーについて説明するものです。説明対象と同じ変更で更新してください。KB には、現時点で確定した意図、つまりプロジェクトがどうあるべきかを記録します。不変条件は、人間が確定させた時点でKBに記録する真実となり、実装済みかどうかは問いません。未確定の意図はKBに記録せず、作業ディレクトリに残します。docs/ は、読者にリリース済みの内容を説明します。コードプロジェクトでこれがブランチ、マージ、リリース済みコードにどう対応するかは、resources/code.md を読み込んでください。

決定記録は例外です。システムが変わった理由を説明できる場合は、置き換えられた決定もそのまま残します。古い決定には置き換え済みであることを記し、後継の決定へのリンクを追加します。

不変条件と現在の選択

確定した各項目は、次の2種類のいずれかとして記録します。不変条件は、どのように作業を進めても守る必要があるものです。現在の選択は、プロジェクトが現時点で採用している、または試しているものです。判断基準は次のとおりです。エージェントがより良い方法を見つけ、それがこの項目に反する場合、まずプロジェクトの担当者である人間に確認すべきでしょうか。そうであれば不変条件です。そうでなければ、エージェントが変更し、ドキュメントを更新します。

原則として現在の選択として扱います。人間の留保を示す表現（「今のところ」「試してみましょう」「そう思います」「手間が少ないほうで」など）は、試行であることを示します。また、人間がエージェントの提案に同意した場合も同様です。人間が不変条件と定めるまでは、エージェント自身の判断も現在の選択として扱います。人間の発言を引用する際は、留保を残し、試行を人間の決定として記録してはいけません。

不変条件は、決定記録または AGENTS.md にルールとして記載します。現在の選択は、説明対象の作業の近くに現状として記載します。測定値と、何が問題だったかを説明する経緯は、測定対象または説明対象の近くに記載し、ルールには含めません。ステータス行には、完了、一部完了、未完了、置き換え済みのいずれかだけを記載します。そこに至った経緯は、バージョン管理またはアーカイブに残します。

KB の規約

構成

KB はほかのディレクトリツリーと同様に、それ自体の AGENTS.md と .context/ の組を持ちます。/creative-writing-skills:qi-layer の指針に沿って記述してください。意図は AGENTS.md に、ガバナンスの詳細（記述規約、構造、検証方法）は .context/ に記載します。書き始める前に、KB 自身の AGENTS.md を読んでください。このスキルはプロジェクト横断の既定として扱い、個々のKBでは、そのKB固有のガイドを優先します。開始時のレイアウト案については、resources/bootstrap.md を参照してください。

Wiki ページの規約

/creative-writing-skills:information-hierarchy に従ってください。1つのドキュメントにつき1つの概念を扱い、ファイル名には作成時期（auth-redesign-notes.md）ではなく、説明対象（token-validation.md）を使います。説明の重複を避け、相互参照を使ってください。用語の方法論については、/creative-writing-skills:shared-dao を読み込んでください。空間に関する内容には Mermaid を使い、ファイルだけでは容易に伝えられない情報を記録します。

運用

取り込み：新しい情報を KB に取り込みます。情報源を読み、重要な知識を抽出して、Wiki ページを作成または更新し、変更の影響を受けるインデックスや相互リンクも更新します。

保守：上記の「現在の事実を履歴より優先する」方針に従って、Wiki を最新の状態に保ちます。

Lint：Wiki の健全性を確認します。矛盾、古くなった記述、孤立したページ、欠落している相互参照を探します。リンクの確認と図の検証には /creative-writing-skills:md-validation を使用します。

人による確認が必要な内容には、> [!FLAG] **Needs human review** を付けてください。