mcpField
P
project-structure

project-structure

github.com/frostney開発0106 回インストール6 日前に更新
リポジトリ

project-structure について

リポジトリの整理や再構成を行うエージェントや開発者向けのプロジェクト構成スキルです。基本的な配置、ガバナンス文書、エージェント向けコンテキスト、完了確認を示し、既存の慣習を尊重して不要な変更を抑えます。

主な機能

  1. 01リポジトリの基本構成ガイド
  2. 02ガバナンス文書の要件
  3. 03AGENTS.md と CLAUDE.md の規則
  4. 04状況に応じた文書参照
  5. 05リポジトリの完了確認

活用シーン

  1. 01新しいリポジトリの整理
  2. 02複数領域プロジェクトの再構成
  3. 03エージェント向けコンテキストの設定
  4. 04完了前のリポジトリ変更確認

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/frostney/known-good-route --skill project-structure

インストール後、Claude Code で/project-structureを入力して読み込まれたか確認します。

同梱ファイルreferences/documentation.mdreferences/tooling.md

詳細

プロジェクト構成

依頼された作業に必要なロールとドキュメントだけを適用します。有効なプロジェクト規約を維持し、構成を大きく変更する場合は、変更前にその選択肢を提示します。言語やスタックに固有のコマンドと設定は、それぞれの言語・スタックのスキルが担当します。

基本構成

エコシステムに応じて、以下のロールに名前を付けます。

  • ルート：ユーザー向けの README.md、マニフェスト、正規のロックファイルを1つ、エージェントのコンテキスト、任意のコントリビューションルール、ガバナンスファイル。
  • ソース：慣例に沿ったソースルートを1つ設け、ドメインまたは名前空間ごとに整理します。
  • テスト：ユニットテストはソースと同じ場所に配置し、エンドツーエンドテストはプロジェクトが管理するトップレベルの場所にまとめます。レイヤー固有のテストは、提供対象となるレイヤー、またはリグレッションが起きやすいレイヤーにのみ追加します。
  • docs/：アーキテクチャ、クイックスタート、ツール、コードスタイル、デプロイメント。
  • スクリプト：単発の自動化処理は scripts/、bin/、または tools/ に配置します。
  • 生成物：無視対象となるビルド／出力先を1つ設けます。
  • 任意：ジェネレーターテンプレート、静的アセット、プロビジョニングされたエージェントスキル。

テストでは、意味のあるリグレッションを検出できるようにします。システムレベルの主な保護網はエンドツーエンドテストです。ユニットテストでは、同じアサーションを重複させずに、公開モジュールの動作を検証します。

ガバナンス

このスタイルを採用するプロジェクトでは、以下の正規のルートファイルを維持します。

  • VISION.md：対象外の範囲を含む、長期的なプロダクトおよび技術の方向性。
  • DEFINITION_OF_READY.md：実装前の必須ゲート。
  • DEFINITION_OF_DONE.md：変更をリリース可能とみなす前の必須ゲート。

複数の領域を含むリポジトリでは、最も近い領域固有のファイルを優先します。ポリシーを重複して記載するのではなく、ガバナンス、エージェント、コントリビューター、プロジェクトの各ドキュメント間を相互にリンクします。ワークフローで必要なガバナンスファイルがない場合は、その不足を明示し、代替ファイルを勝手に作成しないでください。

エージェントのコンテキスト

AGENTS.md を正規のファイルとします。CLAUDE.md は通常のファイルとし、先頭行を @AGENTS.md にして、その後には Claude 固有の追加事項だけを記載します。これは AGENTS.md を直接読み込めない Claude Code セッションを対象とするもので、インポートされた AGENTS.md が二重に読み込まれることはありません。コピーでもシンボリックリンクでもありません。core.symlinks が無効な Windows では、Git がシンボリックリンクを1行のテキストファイルとしてチェックアウトし、Claude Code の Edit と Write ツールはシンボリックリンクを経由した書き込みを拒否するためです。シンボリックリンクまたはコピーされた CLAUDE.md はインポート形式に置き換え、そのリンクに依存していたものも更新してください。

ルートの AGENTS.md は簡潔に保ちます。まずリポジトリを簡単に説明し、その後は、見落としやすい注意点、正確なコマンド、厳守すべき制約、安全上の境界にコンテキストを割り当てます。ファイルツリーや、リポジトリから明らかな規約を繰り返し記載しないでください。

ルールが異なる領域に限り、ネストした <area>/AGENTS.md を追加します。ルートから各領域への参照を記載します。人間によるマージ要件の正式な記載先には CONTRIBUTING.md を使用し、要件を繰り返さずにリンクします。

厳選されたスキルがプロビジョニングされている場合、.agents/skills/ と skills-lock.json はスキルツールによって生成されるものであり、手動で編集してはいけません。.claude/skills は .agents/skills へのシンボリックリンクにします。

状況に応じた参考資料

  • README、ドキュメント、ガバナンスファイル、エージェントファイル、または複数領域から成るリポジトリを作成・再構成する場合は、references/documentation.md を読みます。
  • フック、スクリプト、変更履歴の生成、Markdown／リンク／重複チェック、またはアーキテクチャの乖離検出を導入する場合は、references/tooling.md を読みます。

完了条件

  • リポジトリで宣言されている検証ゲートに合格していること。
  • 作業によって変更されたドキュメントが最新であり、正式な記載先が1つに定まっていること。
  • 生成ファイルが、それを管理するツールを通じて変更されていること。
  • 無関係な構造変更が持ち込まれていないこと。

コメント

Markdown 対応