Communityライティング&編集github.com

Shaelz/codebase-orient-skill

Claude Code および Codex 向けの、再利用可能なコードベース・オリエンテーションスキルです。

codebase-orient-skill とは?

このスキルは、Claude Code や Codex などの AI エージェントが、新規または不慣れなリポジトリを扱う際に、コードベースの現在の状態を体系的に把握するためのものです。`docs/ai/` ディレクトリに、信頼できる情報源に基づいた4つのアーティファクトパッケージを作成または更新することで、エージェントがコンテキストを効率的に取得できるようにします。このスキルは、大規模なリファクタリング、複数ファイルにまたがる実装、エージェントの引き継ぎなど、非自明な作業の前段階で使用するよう設計されています。`docs/ai/` が最新かつ完全な場合、スキルは再実行をスキップし、既存のキャッシュを読み込むことでトークン消費を節約します。また、ドライランモードもサポートしており、実際の書き込み前に変更内容を提案し、承認を待つことができます。発見順序はプロジェクト構造に合わせてカスタマイズ可能で、SvelteKit フレームワークに対する調整済みプローブも含まれています。

対応✓Claude Code✓Codex CLI~Cursor
npx skills add Shaelz/codebase-orient-skill

Installed? Explore more ライティング&編集 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

スキル: codebase-orient

目的

非自明な作業の前に、Claude をこのリポジトリの現在の状態にオリエンテーションします。 docs/ai/ 内に、固定された、出所が明確な4つのアーティファクトパッケージを作成または調整します。 ソースコードとプロジェクト設定が信頼できる情報源であり続けます。

このスキルを使用するタイミング

このスキルを使用するケース

  • 新しい、または不慣れなリポジトリに入るとき
  • リポジトリからしばらく離れた後、新しいセッションを開始するとき
  • 広範囲または複数ファイルにわたる実装作業の前
  • リファクタリング、クリーンアップ、アーキテクチャ計画、エージェントの引き継ぎの前
  • 構造的な変更後: ルート、スキーマ、認証、デプロイ、設定、管理画面
  • docs/ai/ が欠落している、古い、不完全、または内部で矛盾している場合
  • リポジトリ構造、変更範囲、デプロイターゲット、認証動作、管理ルート、コマンド、テストの形状が不明確な場合
  • エージェントが、docs/ai/ 内またはその近くに既にあるものを再発見するために、多くのコンテキストを費やすことになる場合
  • ユーザーが「スキャン」、「オリエンテーション」、「理解」、「マッピング」、「レビュー」、「監査」、「調査」、「慣れる」、「始める前」などと言った場合

このスキルをスキップするケース

  • 単一ファイルに対する小さな、局所的で、既知の編集を行う場合
  • 関連するファイルと変更箇所が既に明確である、1ファイルのバグ修正を行う場合
  • コピーのみ、または文字列のみの変更を行う場合
  • タスクが、現在のコンテキストで既に確認済みのファイルに厳密に範囲が限定されている場合
  • docs/ai/ がちょうど更新されたばかりで、タスクが完全なオリエンテーションを必要としないほど狭い場合

トークン消費を考慮した使用ガイダンス

docs/ai/ はオリエンテーションキャッシュです。新しいキャッシュは、セッションやエージェントの引き継ぎをまたいだ、繰り返しのリポジトリ発見によるトークンコストを削減します。

  • docs/ai/ が最新かつ完全な場合: コンテキストとして読み込み、先に進んでください。オリエンテーションの再実行はスキップしてください。
  • docs/ai/ が古いか欠落している可能性がある場合: スキルを実行してキャッシュを更新してください。初期のトークンコストは、その後の作業全体で償却されます。
  • タスクが小さく、対象ファイルが既に分かっている場合: オリエンテーションをスキップしてください。代わりに対象を絞った読み込みを使用してください。
  • docs/ai/ が既に取得している内容を、エージェントが多くのトークンを費やして再発見することになる場合: キャッシュを更新してください。

オリエンテーションをスキップして構造を推測することでトークンを節約しないでください。広範なリポジトリ発見が繰り返されたり、コストがかかったりする場合は、代わりにキャッシュを更新してください。

オリエンテーション中のハードルール

  • アプリケーションコードやソースコードを変更しないでください。
  • リファクタリングしないでください。
  • コミットしないでください。
  • 記述する前に、主張をソースコードに対して検証してください。
  • すべての重要な主張には、信頼ラベルを付けてください。

通常モード vs ドライランモード

通常モード(デフォルト - ユーザーが指定しない場合に使用します):

  • ソースファイルを読み込むことで、タスクに関連する小さな不確実性を自動的に解決します
  • クリーンなリポジトリでの初回使用時に、完全なパッケージを作成します
  • 現在と完全に一致するクリーンなパッケージを、再作成せずに再利用します
  • 更新または調整のための非特定的なリクエストは、完全な調整として扱います
  • 最後に何が変更されたかを報告します

ドライラン / レポート専用モード(ユーザーが「ドライラン」、「レポートのみ」、「書き込まない」、「最初に変更を提案する」、「監査のみ」、「書き込み禁止」などと言った場合に使用します):

  • 提案された変更を検査し収集します
  • docs/ai/ への編集案を、書き込まずに報告します
  • 書き込む前に明示的な承認を待ちます

モードが指定されていない場合は、デフォルトで通常モードになります。

ライフサイクルと書き込みの安全性

  • 明示的な更新: 現在と完全に一致するパッケージが見つかった後は、ユーザーが明示的に要求した場合にのみ更新または調整します。
  • スコープ指定された更新: ユーザーが明示的に指定したスコープとその直接の依存関係に従います。パッケージ全体の完全なスナップショットを進めたり主張したりせずに、スコープ指定されたカバレッジを記録します。完全なパッケージが存在する前に、部分的なサポート対象パッケージを作成しないでください。
  • レガシー資産の採用: ORIENTATION_STATE.json がない Markdown アーティファクトはレガシー資産です。それらを検査しますが、マニフェストを書き込んだり変更したりする前に、明示的な承認を得てください。承認後はソースから調整します。
  • ダーティツリー: コミットされていない作業を表す状態を書き込む前に、ダーティスナップショットを書き込むか、レポートのみにするかを尋ねてください。ツリーの状態を記録し、クリーンな更新で置き換えられるまで、ダーティとしてマークされたままにします。
  • 使用可能な Git 履歴がない場合: 完全な調整を実行し、リビジョン比較が利用できないことを記録します。
  • 手動編集: Orient はパッケージを所有しています。手動で編集された Orient の状態に対するマージや保存の動作を約束しないでください。

信頼ラベル

  • 事実: コードまたはドキュメントで直接検証済み
  • 強い推論: 複数のファイルによってサポートされている
  • 弱い推論: 可能性はあるが確認されていない
  • 不明: 編集前にさらに調査が必要

主張がどのように確立されたかを区別します:

  • ソース/設定から独立に検証済み: 主張がドキュメントからではなく、実際のソースまたは設定ファイルに対してチェックされた
  • 既存のドキュメントから継承: 主張が CLAUDE.md、README、またはその他のドキュメントから、独立した検証なしに取得された
  • 継承後に検証済み: 主張がドキュメントに由来し、その後ソースに対して確認された
  • パス存在確認済み: ファイルが見つかったが、読み込まれていない
  • 部分読み込み: ファイルの一部が調査されたが、完全なコンテキストを取得していない可能性がある
  • 完全なソース読み込み: ファイルの内容全体が調査された
  • 実装から推測: コードの動作から推定されたもので、明示的に述べられていない
  • コメント/テスト/フィクスチャから推測: 非公式なコンテキストから取得されたもの。せいぜい強い推論として扱う
  • テストによって動作確認済み: テストの実行が成功したことで確認された
  • 不明: 根拠が確立されていない。事実として提示しない

最終レポートとオリエンテーションドキュメントでは、自明でない各主張に上記の起源のいずれかをラベル付けして、読者がどの主張がアクションを起こす前に再検証を必要とするかを判断できるようにします。

発見順序

カスタマイズに関する注意: 以下の発見順序は意図的に幅広く設計されており、ほとんどのプロジェクト形状で編集なしに機能します。特定のプロジェクト向けにファイルパスと順序を調整することもできますが、これはオプションであり、初回使用前に必須ではありません。

以下の順序で実行します:

  1. CLAUDE.md、AGENTS.md、README.md などのプロジェクト指示ファイル(存在する場合) - プロダクトの目的、エージェントルール、プロジェクト規約。 ドキュメントを仮説として扱うルール
    • これらのドキュメントは、権威ある真実ではなく、有用な仮説として扱ってください。
    • アーキテクチャ、ルート、デプロイ、テスト、および信頼できる情報源に関する、影響の大きい事実上の主張を抽出します。
    • それらの主張に依存する前に、ソースコードに対して検証してください。将来の編集に影響を与える可能性のある主張に焦点を当て、すべての文を監査する必要はありません。
    • これらのドキュメントからの主張を、ソース/設定から独立に検証済み または 既存のドキュメントから継承 のいずれであるかをラベル付けせずに CODEBASE_MAP.md にコピーしないでください。
    • 指示ドキュメントがソースが示す内容と比較して古いか誤解を招く場合、その乖離を OPEN_QUESTIONS.md の隠れたリスク報告ルールに従って記録し、ドキュメントの乖離としてラベル付けしてください。
    • 指示レイヤーのトポロジーをマッピングします: どの指示ファイルが存在するか(例: CLAUDE.md、AGENTS.md、.claude/settings.json)、およびどのスコープ(プロジェクトローカル vs ユーザーレベル)かを記録します。これを CODEBASE_MAP.md に記録します。これは将来のエージェントがどのルールが適用されるかを知るのに役立ちます。
  2. プロジェクトマニフェスト(例: package.json、pyproject.toml、Cargo.toml)- 依存関係、スクリプト、ビルド/テストコマンド
  3. ビルドファイルと設定ファイル(例: フレームワーク設定、バンドラー設定)- アダプター、ビルド設定
  4. scripts/ ディレクトリ(存在する場合)- パッケージスクリプトやCIで表現されていない、手動で実行されるツールが含まれている可能性があります
  5. エントリーポイントとルーティングレイヤー - すべてのページ、コントローラー、または API ルート
  6. コアビジネスロジック - ドメインタイプ、モデル、スコアリング、レポートロジック
  7. サーバーサイドサービス - 認証、DB/スキーマ、メール、外部統合
  8. UI/プレゼンテーションレイヤー - コンポーネント、ビュー、テンプレート
  9. 国際化またはコピーファイル - ロケールファイル
  10. リクエストライフサイクル / ミドルウェア - フック、インターセプター、ミドルウェア
  11. データベースレイヤー - マイグレーション、スキーマスナップショット
  12. テスト - テスト構造とカバレッジの形状
  13. ドキュメント - 既存のドキュメント、検証マトリックス。リリース計画、マイルストーン追跡ドキュメント、またはバージョンチャンクログが見つかった場合は、CODEBASE_MAP.md に ## リリースステータス セクションを追加し、現在のバージョン、アクティブなマイルストーン、および次のリリースをブロックしているものを要約します。リリースライフサイクルアーティファクトが存在しない場合は、このセクションを省略します。
  14. 既知の不確実性

フレームワーク固有のプローブ

関連するフレームワークが検出された場合、一般的な発見順序に加えて、これらのプローブを適用します。

この再利用可能なスキルには、現在、SvelteKit 用に調整された明示的なプローブセットが1つ含まれています。他のフレームワークは、将来の実戦または評価エビデンスが専用の調整済みプローブセクションを正当化しない限り、現在は一般的な発見順序を使用します。

SvelteKit

SvelteKit プロジェクトが検出された場合、以下のファイルパターンをグロブします:

  • src/routes/**/+page.svelte: UI ルートページ。各ファイルはルート候補です。トップレベルの src/routes/+page.svelte だけでなく、サブディレクトリも確認してください。
  • src/routes/**/+page.server.ts: サーバーサイドのデータ読み込み、フォームアクション、およびルートレベルのアクセス制御
  • src/routes/**/+layout.svelte: 共有レイアウトシェル
  • src/routes/**/+layout.server.ts: レイアウトレベルの認証、セッション、またはデータのためのサーバーサイドロード関数
  • src/routes/**/+server.ts: API エンドポイントとサーバー専用リクエストハンドラー

サーバーサイドルートファイル(+page.server.ts、+layout.server.ts、+server.ts)は、認証、データ読み込み、フォームアクション、API エンドポイント、およびルートレベルのアクセス制御を理解するために重要です。ルートや変更範囲をマッピングする際にこれらをスキップしないでください。

  • 標準のアプリシェルテンプレートは src/app.html です。
  • svelte.config.js でのアダプターの選択によってデプロイターゲットが決まります - デプロイ関連の主張を行う前に確認してください。

CI/デプロイメントの精度ルール

CI またはデプロイメントワークフローファイルを読み取る際は、運用上重要な詳細を保持してください。具体性をあいまいな要約に落とし込まないでください。

以下を取得して報告します:

  • 並行処理グループ名(どの実行が互いに競合するか)
  • cancel-in-progress の動作 - true の場合、「新しい実行は同じグループの進行中の実行をキャンセルする」と述べ、「並行デプロイを防ぐ」だけではありません。
  • fail-fast の動作
  • デプロイアーティファクトのパス
  • タイムスタンプやハッシュコンポーネントを含む、リリースの命名形式
  • 古いリリースまたはアーティファクトの保持と削除ポリシー
  • 手動 vs 自動トリガー条件
  • 必要なシークレットと環境変数
  • デプロイがその場で上書きするのか、一時パスにステージングするのか、シンボリックリンクを使用するのか、バージョン管理されたリリースディレクトリを使用するのか

CI/デプロイメントの主張には、ワークフローファイルから直接読み取った場合は ソース/設定から独立に検証済み のラベルを付けてください。インシデント中にオペレーターが必要とする精度を失うような方法で、これらの詳細を要約しないでください。

読み込み深さのヒューリスティック

デフォルトでは、すべての大きな CSS ファイル、設定ファイル、生成ファイルを読み込まないでください。

  • 完全読み込み: 要求されたタスクに直接影響するファイル(エントリーポイント、ルーティング、認証、スキーマ、ビルド設定、編集対象ファイル)。
  • 部分読み込みまたはパス確認のみ: 大きなスタイルシート、ベンダーコード、生成された出力、タスクに関連しない設定ファイルなどのセカンダリサーフェス。ファイルのパスのみを確認した場合、または一部を読み込んだ場合は、信頼ラベルで定義されている パス存在確認済み または部分読み込みラベルを使用して、レポートで明示的にその旨を述べてください。
  • スキップ: 明らかに範囲外のファイル(例: バイナリアセット、ロックファイル、テストスナップショット)。ただし、特定の質問によって関連性が生じた場合は除きます。

疑わしい場合は、最初に存在を確認し、主張が必要な場合にのみ完全に読み込むことを優先してください。

パス存在確認 vs 内容読み込み

リスクの低いインベントリの主張(ディレクトリ構造の確認、ファイル数のリスト、設定ファイルが存在することの確認)には、パス存在確認だけで十分です。

主張が動作、アーキテクチャ、リスク、コマンド、デプロイ、認証、ルーティング、または変更範囲に影響を与える場合は、実際のファイル内容を読み込んでください。ファイルの検査が安価であり、その内容がマップに実質的に影響を与える場合に、パス存在確認のみに基づいて主張を ソース/設定から独立に検証済み とラベル付けしないでください。

小さな情報源ファイル読み込みルール

小さなファイルが、プロジェクト全体で使用される語彙や情報源トークンを定義しているように見える場合は、ドキュメントから語彙を継承するのではなく、語彙を検証するのに十分な量を読み込んでください。

これが適用される例:

  • CSS カスタムプロパティトークンファイル
  • ルートまたはメニュー設定ファイル
  • 小さなスキーマまたは定数ファイル
  • コマンドまたはプラグインレジストリ

部分読み込みで十分な場合は、それを使用してください。結果の主張には適切な主張の起源(部分読み込み、完全なソース読み込み)をラベル付けしてください。ファイルを実際に読み込んでいない場合は、それらを ソース/設定から独立に検証済み とラベル付けしないでください。

安価なアーティファクトグロブルール

静的アセット、スクリプト、生成された出力、ドキュメント、テスト、マイグレーション、または設定ファイルの存在や範囲について未解決の疑問を残す前に、安価なパスグロブで解決してください。

試すべき一般的なグロブパターン:

  • static/**/*
  • public/**/*
  • scripts/**/*
  • tests/**/* または test/**/* または spec/**/*
  • .github/workflows/*
  • docs/**/*
  • migrations/**/*
  • dist/**/* または build/**/*

デフォルトで、マッチしたすべてのファイルを深く読み込まないでください。グロブを使用して、存在と範囲の質問を安価に解決してください。特定のファイルの内容が必要な場合にのみ、対象を絞った読み込みでフォローアップしてください。

[以降、翻訳されたコンテンツは元のマークダウン構造を維持して続きます。]

関連スキル