codecontext-setup

Codecontext のセットアップ

エージェントが推測せずに使えるよう、codecontext をセットアップします。

このスキルの目的は、単にパッケージをインストールすることではありません。本来の目的は、リポジトリのエージェント向けルールを一貫したものにすることです。

• ツールチェーンが適切な場所にインストールされている
• AGENTS.md で、エージェントがいつ、どのように使うかを説明している
• インラインの @context を必須の構造化レイヤーとして扱っている
• 補足資料への参照は制約せず、ユーザーの管理に委ねている

必須のサイドカーレのドキュメントスキーマを独自に作らないでください。.ctx.md を必須にしないでください。 参照先は、Markdown、HTML、テキスト、図、エクスポートしたドキュメントなど、リポジトリで使われている解決可能なファイルであれば何でも指定できます。

使用するタイミング

ユーザーから次の依頼があったときに、このスキルを使います。

• codecontext のインストールまたは導入
• @context に関するリポジトリの AGENTS.md またはエージェント向けガイダンスの更新
• プロジェクトで現在使われている codecontext のセットアップの監査
• codecontext ツールとリポジトリの指示の不一致の解消
• エージェントが判断、リスク、前提、履歴を見つけやすくする改善

成果

このワークフローの完了時点で、リポジトリには次の状態が整っている必要があります。

• codecontext に関する明確な AGENTS.md セクション
• エージェント向けの適切な CLI ワークフロー
• リポジトリの言語とツールチェーンに適した強制方法
• 構造化されたサイドカードキュメントに関する誤解を招くガイダンスがない

ワークフロー

1. 現状を監査する

次の項目を確認します。

• パッケージマネージャーとワークスペースの構成
• リポジトリがすでに @recallnet/codecontext-cli に依存しているか
• リポジトリがすでに @recallnet/codecontext-eslint-plugin に依存しているか
• リポジトリに Python、Go、Rust、または他の言語ネイティブの
• リポジトリに、codecontext の強制に適した Python、Go、Ruby、Rust、または他の言語ネイティブの チェッカーがすでにあるか
• ESLint が導入されているか、および共有設定がどこにあるか
• リポジトリのルートやサブツリー／ワークツリーに AGENTS.md があるか
• 既存のエージェント向けドキュメントで、@context、codecontext、ADR、contexts/、または意思決定ログにすでに言及しているか

よくある次の 2 つの問題がないか確認します。

1. ツールはインストールされているが、エージェント向けのワークフローやガイダンスがない
2. ガイダンスはあるが、古い、矛盾している、または存在しないポリシーを参照している

2. インストール範囲を決める

役に立つ最小限の構成をインストールします。

• エージェントが --scope、--diff、または --report を実行する場合は @recallnet/codecontext-cli
• リポジトリで ESLint を使っており、コメントの検証が必要な場合は @recallnet/codecontext-eslint-plugin
• リポジトリの主な強制対象が ESLint 以外の Python、Go、Rust などの場合は、言語ネイティブのチェッカーまたはアナライザー
• リポジトリにパーサー API を直接インポートする独自コードがある場合に限り @recallnet/codecontext-parser

リポジトリで使う予定のないパッケージは追加しないでください。

3. パッケージを変更する前、または変更と並行して AGENTS.md を修正する

エージェント向けの指示がなければ、codecontext のセットアップは不完全です。

リポジトリレベルの AGENTS.md セクションには、次の内容を含める必要があります。

• @context の用途
• 注釈が必要なタイミング
• 推奨する簡潔な分類体系
• 編集前後のワークフロー
• 参照先とは何か、何ではないか
• アンチパターン

サブツリーの AGENTS.md ファイルがリポジトリレベルのポリシーを参照している場合、そのポリシーが実際に存在することを確認してください。

推奨する AGENTS.md のルール

簡潔にまとめます。通常、適切なセクションは箇条書き 8～14 項目に収まります。

次に近い形式にします。

- **codecontext**: Use inline `@context` annotations for non-obvious,
  high-value reasoning that future edits could easily erase.
  - Required for:
    - critical decision logic and invariants
    - security-sensitive behavior and hard-won lessons
    - external integration quirks and contract mismatches
    - regression guards explaining why a simpler change would be wrong
  - Preferred forms: `@context decision`, `@context risk`,
    `@context requirement`, `@context history`
  - Keep notes short and specific: what is true, why it matters, and what
    would break if changed
  - Use `{@link ...}` for supporting material when helpful, but refs are just pointers
    to repo files or docs. Do not require any special doc schema.
  - Before editing critical files, run:
    `npx @recallnet/codecontext-cli --scope <file>`
  - After editing, run:
    `npx @recallnet/codecontext-cli --diff HEAD <file>`
  - For broader orientation in larger repos, run:
    `npx @recallnet/codecontext-cli --report`
  - Do not use `@context` for obvious narration, duplicated ADR prose, or
    generic comments.

リポジトリにベースライン（decision、risk、requirement、history）を超える分類が明らかに必要な場合に限り、分類体系を調整します。追加のカテゴリは必要最小限にしてください。

ADR や大規模なドキュメントツリーがあるリポジトリ向けのガイダンス

リポジトリですでに ADR、計画書、ランブック、またはアーキテクチャドキュメントを使っている場合は、次のようにします。

• @context はインラインのエージェント向けレイヤーとして維持する
• 参照先は任意の詳細情報として扱う
• デフォルトでドキュメントツリー全体を参照するようエージェントに指示しない
• ADR 全体をインラインに複製しない

適切なモデルは次のとおりです。

• @context が構造化されたローカル情報を伝える
• 参照先は任意の補足資料を指定する
• エージェントは必要な場合にのみ参照先を確認する

Refs ポリシー

明確にしてください。

• refs は .md、.html、.txt、図、エクスポート、その他のリポジトリアーティファクトを参照できます
• すべての注釈に refs を付ける必要はありません
• refs によって参照先ファイルのスキーマを強制してはいけません

次のような意味合いを含むガイダンスは記載しないでください。

• .ctx.md が必須である
• frontmatter が必須である
• リンク先ファイルが機械で解析可能でなければならない

CLI ワークフローのガイダンス

CLI がインストールされている場合は、エージェント向けドキュメントで次のコマンドを推奨してください。

npx @recallnet/codecontext-cli --scope path/to/file.ts
npx @recallnet/codecontext-cli --diff HEAD path/to/file.ts
npx @recallnet/codecontext-cli --report

リポジトリの概要把握と意思決定のレビューには --report を使用してください。具体的な編集を行う際は --scope と --diff を使用してください。

適用に関するガイダンス

リポジトリに共有 ESLint 設定がすでにある場合は、プラグインをそこに統合してください。 エージェントに自己チェックさせるのではなく、構文と古い／無効な ref のチェックを一元的に適用することを優先してください。

リポジトリで ESLint を使用していない場合は、codecontext のためだけに無理に導入しないでください。 リポジトリで実際に使われているスタックに適した、標準的な適用手段を優先してください。

• Python リポジトリ：標準チェッカーまたは PyPI 配布ツール
• Go リポジトリ：アナライザー／golangci-lint との統合
• Ruby リポジトリ：標準チェッカー gem または RuboCop 形式の統合
• Rust リポジトリ：crate／Clippy 形式の統合
• 複数言語またはツール非依存のリポジトリ：初期段階では CLI ワークフローで十分な場合があります

重要なのは「ESLint プラグインをインストールしたか」ではありません。 「このエコシステムでは、実際に何が @context の正しさを適用しているか」です。

レビューで確認すること

次の項目はセットアップ上の不備として指摘してください。

• リポジトリに存在しないポリシーを参照している子 AGENTS.md ファイル
• @context に言及しているものの、ワークフローを示していない指示
• 大規模なリポジトリで --report を無視しているワークフローのガイダンス
• リンク先のドキュメントを必須の構造化サイドカーとして扱うガイダンス
• 対応するエージェント向けドキュメントを伴わないパッケージのインストール
• デフォルトでエージェントに巨大な ADR／ドキュメントツリーを読むよう指示するドキュメント

作業の完了

セットアップまたは監査を終えたら、次の内容を伝えてください。

1. インストールまたは変更したもの
2. 修正した古い、または矛盾する AGENTS.md のガイダンス
3. 残っている不足事項
4. 適用手段をインストールしなかった場合は、その理由

デフォルトの推奨事項

リポジトリに既存の codecontext ガイダンスがない場合は、最初に複数の子ドキュメントへ指示を散在させるのではなく、ルートの AGENTS.md に codecontext-setup セクションを作成することを推奨します。