2025年のリポジトリのファイル構成

私が2025年に見直したGitHubリポジトリのファイル構成メモです。いわゆる.editorconfigとか.github的なディレクトリをイメージしてください。「AI回りのファイル管理、GitHubメタ情報の管理、CI/CD」+「言語ごとの構成パターン」という組み合わせですが、2025年になってAI回りのファイル管理が徐々に細かくなってきた感じがあります。

基本構成
AI
必ず含んでいるファイル
プログラム
- C#
- Go
- TypeScript
まとめ
参考

基本構成

以下の構成がベースになります。(*)は作成するかどうかはリポジトリによって変わるファイルです。言語を問わず共通する構成で、これに言語ごとの構成が加わります。

$ tree -L 2 -a --dirsfirst
.
├── .github
│   ├── copilot-instructions.md
│   ├── agents
│   │    ├── frontend.agents.md (*)
│   │    ├── backend.agents.md (*)
│   │    └── LANGUAGE.agents.md (*)
│   ├── instructions
│   │    ├── basic.instructions.md (*)
│   │    └── LANGUAGE.instructions.md (*)
│   ├── CODEOWNERS
│   ├── dependabot.yaml
│   └── workflows
│        ├── build.yaml
│        ├── release.yaml
│        └── stale.yaml
├── .dockerignore (*)
├── .editorconfig
├── .gitattributes
├── .gitignore
├── AGENTS.md (*)
├── LICENSE
├── README.md
└── aqua.yaml (*)

AI

AI支援機能は主にGitHub Copilotを使っています。ClaudeもCopilot経由で使うことが多い¹です。この利用方法だと、AI関連のファイルは次の通りです。

.
├── .github
│   ├── copilot-instructions.md
│   ├── agents
│   │    ├── frontend.agents.md (*)
│   │    ├── backend.agents.md (*)
│   │    └── LANGUAGE.agents.md (*)
│   └── instructions
│        ├── basic.instructions.md (*)
│        └── LANGUAGE.instructions.md (*)
└── AGENTS.md (*)

特にCopilotのリポジトリインストラクションには以下のような内容を含めています。プロンプトは使っていないので定義していませんが、2026年はプロンプトも定義する予定です。

インストラクション
- .github/copilot-instructions.md: 全体の基本方針
- .github/instructions/xxxxx.instructions.md: 対象ファイルを絞りつつ個別のインストラクション
- AGENTS.md: claudeを用いる場合のエージェントインストラクション。copilot-instructions.mdのシンボリックリンク
エージェント
- .github/agents/xxxxx.agents.md: 特定の役割を持つカスタムエージェントのインストラクション

私はグローバルインストラクションを用いず、リポジトリインストラクションを設定して、そのリポジトリに特化した応答を得られるようにしています。例えば、C#リポジトリならC#に特化したインストラクション、フロントエンドリポジトリならTypeScriptやcssに特化したインストラクションを用意しています。

GitHub PRコードレビュー時もCopilotを使うため、.github/copilot-instructions.mdにはコードレビューでも同様に使える想定で書いています。ただ、この記事のようにPRコードレビューを条件としたインストラクションでもよさそうです。

今のところ、スペック駆動開発は微妙に感じていて、個人開発では使っていません。こればかりは試行錯誤が必要な感触です。

必ず含んでいるファイル

以下のファイルは、どのリポジトリでも必ず含んでいます。copilot-instructions.md以外を軽く説明します。

.
├── .github
│   ├── copilot-instructions.md
│   ├── CODEOWNERS
│   ├── dependabot.yaml
│   └── workflows
│        ├── build.yaml
│        ├── release.yaml
│        └── stale.yaml
├── .editorconfig
├── .gitattributes
├── .gitignore
├── LICENSE
└── README.md

Gitリポジトリメタファイル

Gitリポジトリのメタ情報を管理するファイルは以下の通りです。

.
├── .github
│   ├── CODEOWNERS
│   └── dependabot.yaml
├── .gitattributes
├── .gitignore
├── LICENSE
└── README.md

LICENSEはいうまでもないですが、2025年になってLICENSE.mdでなくLICENSEに変えました。GitHubしか使わないのでどっちでもいいのですが、意外とツールはLICENSEを期待していることが多いためです。

README.mdは、なるべく単一ファイルで書くほうがいいと考えています。コンテキストごとに複数ファイルへ分割するか、とか100回ぐらい考えるのですがリンク踏む、検索しにくさは思ったより大きいです。このため単一README.mdにいっぱい書くのも悪くない派です。

.gitattributesは、主に改行コードやリポジトリの言語除外設定に使っています。

.gitignoreは、リポジトリルート一か所にしています。とはいえ、1リポジトリ内で複数言語を用いる場合、言語ごとのルートフォルダで.gitignoreを分けることもありますが避けたいところです。

CODEOWNERSは、最近になって全リポジトリに配置しました。これはGitHubの仕様変更に伴うもので、リポジトリを作成しても作成者でもWatchされなくなったためです。CODEOWNERを設定すると、DependabotのPRや外部PRが来たときに自動でレビュアに追加、通知されます。ただ、あまりにもPRが多いリポジトリでは通知が煩わしくなるので、その場合はCODEOWNERSを意図的に外したほうがいいです。

dependabot.yamlは、リポジトリの依存関係をDependabotに自動更新させるための設定ファイルです。過去の記事でも設定を紹介していますが、更新頻度をある程度抑えつつ、最新への追随は検討する感じです。

個人的に、ISSUE_TEMPLATEやPULL_REQUEST_TEMPLATEはあまり使わない派です。用意したところで使われないので、自己満足に陥りやすくて諦めています。しょうがない。

.editorconfig

どのリポジトリでも共通のコードスタイルやフォーマットを保つために.editorconfigを使っています。IDEやエディタが対応していれば自動的に適用されるので便利です。

.
└── .gitattributes

.editorconfigがないリポジトリは扱いが面倒です。2025年になっても配置していないリポジトリは時々ありますが、2024年までと比べてだいぶん減ってきました。良いことでもあるし、使っていないリポジトリはそれだけ興味ないんだなというのもわかりやすくなってきました。その割に、GitHubのサポート薄くて.editorconfigって立ち位置が微妙な気もしています。

GitHub Workflows

言語が異なっても、OSSにおけるCI/CDの基本的な流れは同じなのでGitHub Workflowsもほぼ共通化しています。主に、ビルド、リリース、古いIssue/PRの自動クローズの3つが安パイです。これに加えて、サンドボックス実行だったり、lint実行だったりを追加することもあります。

$ tree -L 2 -a --dirsfirst
.
├── .github
│   └── workflows
│        ├── build.yaml
│        ├── release.yaml
│        └── stale.yaml
└── aqua.yaml (*)

aqua.yamlは、外部ツールAquaをGitHub Actionsで使う場合に配置しています。

プログラム

プログラミング系のソースコードは、その言語ごとに配置しています。言語ごとにやり方が違うので、一概に言えないのですが、C#、Go、TypeScriptを例にします。Swiftはアプリの実装に依存しており、まだ一般解を持っていないため割愛します。

C#

C#の場合、ソリューションファイル、Directory.Build.props、Directory.Packages.propsをルートに置き、ソースコード、テストコード、サンプルコードをそれぞれsrc、tests、samplesディレクトリに分けています。時々、samplesではなくsandboxにすることもあります。

C#は、.editorconfigに言語のフォーマットルールを定義できるため、C#ライブラリやプロジェクトにおいて.editorconfigは必須と言えます。また、Directory.Build.propsやDirectory.Packages.propsを使うことで、プロジェクト全体で共通の設定やパッケージバージョンを管理できるため、これらも必須と考えて差し支えないです。ソリューションファイルは、.slnx形式が推奨です。私のメンテしているプロジェクトはすべて.slnxに移行しました。²

.
├── samples
│   └── ConsoleApp
├── src
│   └── LibraryName.FooBar
├── tests
│   └── LibraryName.FooBar.Tests
├── .editorconfig
├── Directory.Build.props
├── Directory.Packages.props
└── LibraryName.slnx

Go

Goの場合、cmd、internal、pkgディレクトリをルートに置くことが多いです。cmdにはアプリケーションのエントリポイントを、internalには内部パッケージを、pkgには外部に公開するパッケージを配置します。Goはこじんまりしたプロジェクトが多いので、主にcmdとinternalのみ使うことが多いです。

Goは「テストファイルがソースコードのすぐそばに配置される」のがすごくいいです。手放しで好きです。

.
├── cmd
│   └── appname
├── internal
│   └── package1
├── pkg
│   └── package2
├── .editorconfig
├── go.mod
└── go.sum

TypeScript

TypeScriptの場合、srcディレクトリにソースコードを、testsディレクトリにテストコードを配置します。ビルド設定や依存関係はtsconfig.jsonやpackage.jsonで管理します。パッケージ回りがカオスすぎてnpmで様子見ていますが、最新パッケージの更新を遅らせるminimumReleaseAgeがいい感じなのでpnpmに戻る日も近い説あります。

.
├── src
│   └── index.ts
├── tests
│   └── index.test.ts
├── .editorconfig
├── package.json
└── tsconfig.json

まとめ

2025年の私のGitHubリポジトリの基本的なファイル構成でした。今年はAI回りで構成がころころ変わったのですが、来年もまた変わることでしょう。リポジトリを作るたびにあれってなることがあるのですが、テンプレートリポジトリにはしたくない感じがあります。いろんな言語使うのと、既存のリポジトリにも展開するのでテンプレートリポジトリは、なんか違うんですよね。

リポジトリのファイル構成、こうしてるよっていうのが2025年はいくつかあり参考になりました。来年もそういうのを読めるといいなー。