qi-layer

qi-layer

/creative-writing-skills:qi-maintenance は、変更内容とともに移動させる必要がある、同じ場所に置かれたナレッジを管理します。 このスキルは、そのナレッジの書き方と構成方法を扱います。

各レイヤーの配置場所と内容については、/creative-writing-skills:knowledge-layers を読み込んでください。 まだ読み込まれていない場合は、/creative-writing-skills:llm-writing を読み込んでください。

このスキルでは、ディレクトリ内にある次の一組のファイルをどのように記述し、保守するかを扱います。 AGENTS.md と .context/CONTEXT.md です。この一組のファイルは、エージェントが作業するあらゆるツリー（コード、KB、ドキュメント、作業ディレクトリ）を統括します。AGENTS.md は、エージェントの限られたコンテキストに恒常的な指示として読み込まれます。プロンプトのように、簡潔に、すべての行に意味を持たせて書いてください。

4 つの原則

1. フラクタル圧縮：末端の AGENTS.md は、そのディレクトリの内容を要約します。親の AGENTS.md は、子ディレクトリを要約します。各レベルは、ひとつ下のレベルを圧縮したものです。
2. 階層的な要約：ルートには広範なアーキテクチャの全体像を記載します。末端にはローカルな作業知識を記載します。エージェントは下位へ進むにつれ、理解を深めていきます。
3. 最小共通祖先での重複排除：複数のパスに共通するナレッジは、関連するすべてのパスを含む最も浅いノードに一度だけ記載します。
4. 段階的な開示：このレベルで正しく作業するために必要な情報だけを記載します。詳しい情報については .context/CONTEXT.md にリンクします。

AGENTS.md の書き方

エージェントは、ツリー内のほかのファイルを開く前に AGENTS.md を読みます。その時点で読むことを想定して書いてください。ここで作業する前に、誰かが理解しておくべきことは何か？ と考えます。それを AGENTS.md に記載します。

ディレクトリの性質に応じて、AGENTS.md はできるだけ短く保ち、200 行を超えることはほとんどないようにしてください。実質的な内容だけを含めます。

• 目的：この領域が何であり、何ではないか（1〜3 文）
• メンタルモデル：この領域をどう捉えるか、主要な抽象概念
• 主要なルール：制約事項、誤ると何が壊れるか
• アンチパターン：ここでしてはいけないこと
• 下位へのリンク：詳細情報は .context/ へ、関連領域へのリンクも記載

AGENTS.md だけを読むエージェントでも、ここで正しく作業できる必要があります。.context/ も読むエージェントなら、安全に変更を加えられる必要があります。

.context/CONTEXT.md の書き方

詳細な情報は、説明対象と同じ場所に置きます。エージェントが契約、アーキテクチャ、根拠の詳細を必要とするときに参照する場所です。

セクション（実質的な内容があるものだけを使用します）：

• 契約：インターフェース、不変条件、違反した場合に何が壊れるか
• アーキテクチャ：コンポーネント間の関係、データフロー、依存関係の方向
• 根拠：Y ではなく X を選んだ理由、却下した代替案
• パターン：この領域での作業方法、具体的な落とし穴

.context/ ディレクトリは拡張可能です。特定の関心事を扱う追加ファイルを CONTEXT.md と並べて配置できます。

AGENTS.md に記載しないもの

毎セッションのテストを適用します。ルートの AGENTS.md は毎回のセッションで読み込まれます。特定の領域で作業するときにだけ必要なナレッジは、ルートではなく、その領域の AGENTS.md または .context/ に記載します。

思考か参照かのテストを適用します。削除すると誤った判断につながる文章は、AGENTS.md に記載します。エージェントが単に参照する必要があるだけの情報は、.context/ に記載します。動作に影響しない文章は削除します。エージェントはすでに、作業に必要なスキルと一般的な規約を理解しています。

具体的な失敗パターン：

• セッション情報の混入：LLM の作業メモが指示ファイルに固定化したものです。目印としては、「deleted」「shipped」「deferred」といったステータス更新の表現、文脈の説明がない実装用語の羅列、履歴の説明があります。
• 意図を装う参考資料：表、コマンドブロック、スキームの語彙一覧、実装の詳細。
• 冗長なガード：テスト、型、バリデーターなどのチェックで既に強制されている不変条件を、文章で警告することです。実際のガードはチェックです。文章はより早く劣化します。
• ナレッジの重複：スキル、ドメインの .context/、KB ページにある内容を繰り返すことです。記載場所へリンクしてください。
• ルートに置かれたドメイン固有の詳細：URI スキームの表、ゲートウェイの料金体系の内部情報、認証の実装詳細などです。これらはルートではなく、各ドメインの AGENTS.md に記載します。

構造上のルール

• すべてのリンクに相対パスを使用します
• AGENTS.md と .context/ は同じディレクトリ階層に配置します（兄弟関係）
• 見出しではなくファイルにリンクします（見出しは変更されることが多いためです）
• .context/ ディレクトリ間で、相互の契約を記述した横断リンクを設けます
• LCA による重複排除：兄弟ディレクトリが同じコンテキストを共有する場合は、親ディレクトリに記述します

CLAUDE.md

Claude Code は、ディレクトリに CLAUDE.md がない場合に AGENTS.md を読み込むため、ほとんどのディレクトリでは AGENTS.md だけで十分です。Claude 固有の指示がある場合にのみ CLAUDE.md を追加し、最初の行に @AGENTS.md を記述します。CLAUDE.md が存在すると、Claude は AGENTS.md の代わりにそれを読み込むためです。共通の指示を CLAUDE.md に記述してはいけません。

読み込み方法は階層によって異なります。ルートでは、すべてのハーネスが各セッションで AGENTS.md を読み込みます。サブディレクトリでは、Claude はその場所のファイルにアクセスすると、そこにあるネストされた AGENTS.md を読み込みます。他のエージェントは、そのディレクトリに入る際にネストされた AGENTS.md を読んだ場合にのみ、その内容を確認します。各ネストされた AGENTS.md は、それを読むエージェントに合わせて記述します。エージェントがそのディレクトリに入ったときに必要なローカルの追加情報を記載し、それ以外の内容は祖先ディレクトリから継承します。