🤖

AIエージェント開発のススメ：Claude CodeでPJTを立ち上げるときの初期設定

に公開
Go
TypeScript
TDD
AI駆動開発
Claude Code
tech

AIエージェント開発のススメ

Claude Code などのAIエージェントを使って、実運用プロジェクトや学習用プロジェクトをいくつか立ち上げてきました。

その中でわかってきたのは、AIエージェント開発では「最初の設定」と「開発ルール」がかなり重要だということです。

AIエージェントは非常に速くコードを書いてくれます。
一方で、ルールやテストが弱い状態で進めると、過去に作った機能を壊したり、READMEや設計方針と実装がズレたりすることがあります。

この記事では、自分が Claude Code でプロジェクトを立ち上げる際に意識している初期設定や開発方針をまとめます。

自分自身のメモとしても、今後更新していく予定です。

前提

この記事は、主に以下のような開発を想定しています。

  • Claude Code を使ったAIエージェント開発
  • Next.js / TypeScript などのモダンWeb開発、Android/iOSアプリなどにもほぼ併用可能
  • 学習用または公開用GitHubリポジトリ
  • AIに実装を任せつつ、人間がレビュー・動作確認する開発スタイル
  • 小さなフェーズ単位で実装していくプロジェクト

1. everything-claude-code を入れる

まず、Claude Code 向けの補助リソースとして everything-claude-code を入れます。

Claude Codeの使い方、設定、コマンド、ワークフローなどを把握するための情報源として便利です。

導入方法そのものも、Claudeに聞きながら進めれば問題ありません。

everything-claude-code を確認して、このプロジェクトで使えそうなClaude Codeの設定や運用ルールを提案してください。

AIエージェント開発では、AIにコードを書かせるだけではなく、AIをどう使うか自体も継続的に改善していく必要があります。

2. awesome-design-md を使う

UIを含むプロジェクトでは、awesome-design-md のようなデザイン指示用のMarkdownを使うと便利です。

AIエージェントにUIを作らせる場合、単に

いい感じの管理画面を作って

と指示すると、デザインの一貫性が崩れやすくなります。

そのため、プロジェクト内に DESIGN.md のようなファイルを置き、以下のような内容を明文化します。

  • カラーパレット
  • フォントサイズ
  • 余白
  • 角丸
  • ボタンやカードの見た目
  • レイアウト方針
  • レスポンシブ方針
  • UIの雰囲気

例：

# DESIGN.md

## Visual Direction

- Clean B2B SaaS dashboard
- Calm and professional
- High readability
- Minimal decoration

## Colors

- Background: #F8FAFC
- Surface: #FFFFFF
- Primary: #2563EB
- Text: #0F172A
- Muted: #64748B
- Border: #E2E8F0

## Layout

- Sidebar width: 240px
- Header height: 64px
- Card radius: 12px
- Section spacing: 24px

このようにデザインの前提をMarkdown化しておくと、AIエージェントがUIを生成するときのブレを減らせます。

3. 「安定重視すぎる技術選定」を避ける

AIに技術選定を任せると、かなり安全寄りの構成を提案してくることがあります。

もちろん安定性は重要です。
ただし、学習用・公開用リポジトリの場合、人から見たときに「少し古い構成では？」と見えることもあります。

そのため、自分は最初に以下のように伝えるようにしています。

このプロジェクトでは、古すぎる安定版ではなく、現在の実務・求人・公開リポジトリで見ても違和感のないモダンな構成を優先してください。

ただし、実験的すぎる技術や破壊的変更が多すぎるものは避けてください。

ポイントは、単に最新を追うのではなく、

モダンでありつつ、実務でも使える範囲

を狙うことです。

また、AIにモジュールやライブラリをインストールさせる場合は、指定されたバージョンが古すぎないかを確認します。

過去の事例では、AIが最新安定版ではなく、少し古いバージョンを指定することがありました。

そのため、package.json、composer.json、Dockerfile、各種インストールコマンドなどを確認し、現在の実務で使っても違和感のないバージョンかを精査させるようにしています。

例：

使用している主要ライブラリ、フレームワーク、Dockerイメージ、開発ツールのバージョンを確認し、古い安定版が指定されていないか、最新安定版に近い構成になっているかを確認してください。

4. npmではなくpnpmを基本にする

自分のプロジェクトでは、基本的に pnpm を使う方針にしています。

理由は以下です。

  • インストールが速い
  • ディスク効率が良い
  • monorepo と相性が良い
  • 最近のモダンフロントエンド構成でよく見る
  • lockfile を含めて依存関係を管理しやすい

初期化時には、Claudeに次のように伝えます。

このプロジェクトでは npm ではなく pnpm を使用してください。
package manager は pnpm 前提で、READMEやセットアップ手順もpnpmで統一してください。

また、AIエージェントが途中で npm install を混ぜてしまうことがあるため、ルールファイルにも明記しておきます。

## Package Manager

- Use pnpm only.
- Do not use npm or yarn.
- Do not generate package-lock.json or yarn.lock.

AIエージェント開発では、こういった細かいルールを書いておかないと、途中で勝手に混ざることがあります。

5. AIまわりの情報収集は必須業務

AIエージェント開発は変化が速いです。

Claude Code、Cursor、MCP、Figma連携、GitHub連携、AI用のルールファイル、各種テンプレートなど、短期間で状況が変わります。

そのため、XやGitHubなどでAIまわりの情報をキュレーションすることも、AIエンジニアにとっては実務の一部だと考えています。

ただし、新しいツールやテンプレートを入れる場合は、セキュリティ面も確認する必要があります。

  • 依存パッケージに問題がないか
  • 不要な外部送信がないか
  • APIキーや秘密情報を扱っていないか
  • GitHub Actionsで危険な処理をしていないか
  • ライセンス上の問題がないか

疑わしい場合は、AIにそのまま相談します。

このリポジトリを導入する前に、セキュリティ上の懸念点、依存パッケージ、ライセンス、GitHub Actionsの危険性を確認してください。

AIを使う場合でも、最終判断は人間が行う必要があります。

6. TDDを前提にする

AIエージェント開発で特に重要だと感じているのが、TDDです。

AIは新しい機能を作るのは得意です。
一方で、過去に作った機能や既存の仕様を壊してしまうことがあります。

そのため、テストを積み上げて、常にオールグリーンの状態を維持する必要があります。

特にNext.js / TypeScriptのプロジェクトでは、以下を入れることが多いです。

  • Vitest
  • React Testing Library
  • ESLint
  • TypeScript typecheck
  • Playwright
  • Storybook

最低限、以下のコマンドで確認できるようにします。

{
  "scripts": {
    "lint": "next lint",
    "typecheck": "tsc --noEmit",
    "test": "vitest",
    "test:run": "vitest run",
    "check": "pnpm lint && pnpm typecheck && pnpm test:run"
  }
}

AIエージェントには、実装前にこう指示します。

仕様を変更する前に、まず失敗するテストを追加してください。
その後、最小限の実装でテストを通してください。
最後にリファクタリングしてください。

AIに任せるからこそ、テストが必要です。

Goのプロジェクトであれば、以下のような検証を基本にします。

  • gofmt
  • go vet
  • go test
  • golangci-lint
  • staticcheck
  • templ generate（Templを使う場合）
  • go build

最低限、以下のようなコマンドで確認できるようにします。

go fmt ./...
go vet ./...
go test ./...
go build ./...

Templを使う場合は、テンプレート生成も確認対象に含めます。

templ generate
go test ./...

Goの場合は、言語標準の gofmt や go test が強力なので、まずは標準ツールを確実に通すことを重視します。
そのうえで、必要に応じて golangci-lint や staticcheck を追加します。

7. コードは人間が読めることを重視する

AIエージェントは短時間で多くのコードを生成できます。

しかし、生成速度を優先しすぎると、人間が読みにくいコード、意図が追いにくいコード、責務が曖昧なコードになってしまうことがあります。

そのため、AIエージェントには「動けばよい」ではなく、人間がレビューしやすく、あとから保守しやすいコードを書くように指示します。

具体的には、以下を重視します。

  • 関数やクラスの責務を小さくする
  • 変数名・関数名は意味が分かる名前にする
  • 複雑な条件分岐にはコメントを入れる
  • なぜその処理が必要なのかをコメントに残す
  • 一時的な実装や妥協点は TODO として明記する
  • 巨大な関数やファイルを作らない
  • 実装意図が分かりにくいコードを避ける

コメントは、単に処理を日本語化するためではなく、判断理由や仕様上の注意点を残すために使います。

例：

この処理は、予約が重複しないように同一スタッフ・同一時間帯の予約を事前に確認する。
Redisロックだけに依存せず、DB側でも最終チェックを行う。

AIに任せる場合でも、最終的にコードを読むのは人間です。

そのため、AIエージェントには、実装後に「人間が読んで理解しやすいか」「コメントが不足していないか」「責務が大きすぎないか」を確認させます。

8. DDDやClean Architectureを意識して責務を分ける

AIエージェントに実装を任せる場合でも、場当たり的にファイルを増やすのではなく、責務を分けた設計にすることが重要です。

特にAPIや業務ロジックを含むプロジェクトでは、DDD、Clean Architecture、Layered Architecture などの考え方を参考にし、ドメインロジックと外部都合の処理を分離します。

たとえば、以下のように責務を分けます。

  • domain：業務ルール、エンティティ、値オブジェクト
  • usecase：アプリケーションの処理手順
  • infrastructure：DB、外部API、ファイル、メールなどの外部接続
  • presentation：Controller、API Route、画面表示
  • tests：単体テスト、結合テスト

このように分けることで、DBやフレームワークを変更しても、業務ロジックへの影響を小さくできます。

AIエージェントには、以下のように指示します。

DDDやClean Architectureを意識し、業務ロジックをControllerやAPI Routeに直接書かないでください。
domain、usecase、infrastructure、presentation の責務を分けて実装してください。
ただし、学習用・小規模プロジェクトでは過剰設計にならないように、必要な範囲でシンプルに構成してください。

重要なのは、アーキテクチャ名を使うこと自体ではなく、業務ルールとフレームワーク都合のコードを混ぜすぎないことです。

9. pre-commit / pre-push を設定する

AIエージェント開発では、commit前の検証も重要です。

自分は、以下のような方針にしています。

pre-commit = 壊れたコードをコミットさせない
pre-push = 壊れたブランチをpushさせない
CI = チーム全体の品質ゲート

たとえば husky と lint-staged を使い、commit前に以下を実行します。

  • format
  • lint
  • typecheck
  • unit test

例：

pnpm lint-staged
pnpm typecheck
pnpm test:run

pre-pushでは、もう少し重い検証を入れます。

pnpm build
pnpm storybook:build
pnpm test:run

重要なのは、AIが生成したコードをそのまま信じないことです。
機械的な検証を通してから、人間が差分と動作を確認します。

10. commitはAI、pushは人間

自分の運用では、できれば以下の分担にしたいと考えています。

commit = AIエージェント
push = 人間

AIエージェントには、フェーズごとに小さくcommitしてもらいます。

ただし、pushは人間が行います。

理由は、push前に以下を確認したいからです。

  • 実際に動作するか
  • 余計なファイルを変更していないか
  • READMEやドキュメントが実装とズレていないか
  • テストが通っているか
  • セキュリティ上の問題がないか
  • コミット粒度が適切か

AIエージェントは作業者として非常に優秀ですが、最終的な責任は人間が持つべきです。

また、commit前には、今回の変更内容に対応する単体テストの作成漏れがないかも確認します。

AIエージェントは実装を進める速度が速い一方で、正常系の実装だけを先に進め、テスト追加が後回しになることがあります。

そのため、commit単位で以下を確認します。

  • 今回の変更に対応する単体テストが追加されているか
  • 既存仕様を変更した場合、既存テストも更新されているか
  • 正常系だけでなく、異常系や境界値も必要に応じて確認されているか
  • テストを追加できない場合、その理由がコメントやドキュメントに残っているか

AIエージェントには、commit前に次のように確認させます。

今回の差分を確認し、変更内容に対応する単体テストの作成漏れがないか確認してください。
新しいロジック、条件分岐、バリデーション、APIレスポンス、エラーハンドリングを追加・変更している場合は、対応するテストを追加または更新してください。
テスト追加が不要な場合は、その理由を説明してください。

11. ローカル開発を前提にする

AIエージェント開発でも、ローカル開発環境は重要です。

クラウドIDEやブラウザ上の開発環境も便利ですが、実務ではローカルでないと確認しにくいことも多くあります。

  • ブラウザでの表示確認
  • 環境変数の確認
  • ローカルDBやエミュレータ
  • Figma / MCP / Claude Code との連携
  • Git hook
  • PlaywrightのE2Eテスト
  • Dockerを使った検証

特にClaude Codeを使う場合、ローカルのリポジトリに対して直接ファイル操作させることで、開発速度が上がります。

そのため、プロジェクト初期に以下を整えます。

  • .env.example
  • READMEのセットアップ手順
  • pnpm scripts
  • Git hooks
  • テストコマンド
  • ローカル起動手順

12. 最初に /plan でロードマップを作らせる

実装に入る前に、まずAIエージェントに計画を作らせます。

Claude Codeであれば、最初に /plan を使って、フェーズとステップを整理させます。

例：

このプロジェクトを、AIエージェント開発前提で進めます。

まず実装せずに、以下を含むロードマップを作成してください。

- 技術構成
- ディレクトリ構成
- フェーズ分割
- 各フェーズの完了条件
- テスト方針
- pre-commit / pre-push 方針
- README更新方針
- AIエージェント運用ルール

この段階では、すぐに実装させません。

まずは生成された計画を読み、人間が問題ないか確認します。

特に以下を見ます。

  • フェーズが大きすぎないか
  • 最初から作り込みすぎていないか
  • テストが後回しになっていないか
  • 技術選定が古すぎないか
  • READMEやドキュメント更新が含まれているか
  • CIやGit hookが後回しになっていないか

計画に問題がなければ、フェーズごとに実装していきます。

ローカルIssueで作業単位を管理する

初期フェーズでは、READMEにTODOや進捗を書かせる方が高速に進められます。

ただし、開発が進むにつれてREADMEにフェーズ、TODO、作業ログ、設計メモが溜まり、READMEが肥大化しやすくなります。

そのため、ある程度プロジェクト構成が固まった段階で、作業単位のタスクは .claude/issues/ 配下のMarkdownファイルとして管理します。

.claude/issues/001-initial-setup.md
.claude/issues/002-auth-feature.md
.claude/issues/003-admin-dashboard.md

各Issueファイルには、目的、作業内容、完了条件、確認コマンド、作業ログ、結果を記録します。

このIssueは、作業前にはAIエージェントへの指示書として使い、作業後には「いつ、何を、どこまで行ったか」を残す作業履歴として使います。

GitHub IssuesやNotionも便利ですが、外部サービスに依存します。
Claude Codeのようにローカルリポジトリを直接扱うAIエージェントでは、ローカルIssueとしてMarkdownファイルを管理する方が、AIが読み書きしやすく、Gitの履歴にも残せます。

READMEは入口、.claude/issues/ は作業チケット、.claude/project-status.md は全体進捗、docs/ は設計資料、という役割分担にすると、READMEを肥大化させずにAIエージェント開発を継続できます。

13. ヘルプ・マニュアルはClaudeに任せる

ヘルプやマニュアルの作成は、Claudeに任せるとかなり効率が良いです。

自分は、基本的にMarkdown形式で出力させるようにしています。

新規プロジェクトであれば、仕様や画面構成をもとにヘルプを作成させます。
途中から入ったプロジェクトであれば、まずソースレビューをさせて、現在の仕様を把握させます。

そのうえで、以下のように出力させます。

このプロジェクトのソースをレビューして、現在の仕様を把握してください。
そのうえで、ユーザー向けヘルプと開発者向けマニュアルをMarkdown形式で作成してください。

この出力結果を読むことで、人間側も仕様の再確認ができます。

つまり、Claudeにマニュアルを書かせることは、単なるドキュメント作成だけではありません。

  • 仕様の棚卸し
  • 実装とのズレの確認
  • 画面や機能の抜け漏れ確認
  • ユーザー視点での説明確認
  • 開発者向け引き継ぎ資料の作成

こういった効果があります。

14. claude.md や .claude に進捗を管理させる

AIエージェント開発では、セッションが切れたり、日をまたいだりすることがあります。

そのため、進捗管理をAI側に任せられるようにしておくと便利です。

たとえば、以下のようなファイルを置きます。

claude.md
.claude/project-status.md
.claude/roadmap.md
.claude/decisions.md

内容としては、以下を管理させます。

  • 現在のフェーズ
  • 完了した作業
  • 未完了の作業
  • 次にやること
  • 技術的な決定事項
  • 注意点
  • テスト状況
  • 既知の問題

セッションを切るときは、毎回細かく指示しなくても、

進捗を記録してください。お疲れさまでした。

で十分です。

これにより、次回セッションでAIが状況を復元しやすくなります。

AIエージェントに作業を任せるなら、ソースコードだけでなく、作業状態もファイルとして残すことが重要です。

15. READMEやドキュメントを常に最新にする

AIエージェント開発では、READMEやドキュメントが古くなりやすいです。

実装は進んでいるのに、READMEのセットアップ手順が古い。
使っている技術は変わったのに、ドキュメントだけ古い。
完了済みのフェーズが未完了のままになっている。

こういうことがよく起きます。

そのため、AIエージェントには以下をルール化します。

## Documentation Rules

- Update README.md when setup steps change.
- Update docs/roadmap.md when a phase is completed.
- Update docs/decisions.md when technical decisions change.
- Do not mark a task as completed unless tests pass.

READMEも成果物の一部です。

特に公開リポジトリでは、READMEが整っているかどうかで印象が大きく変わります。

16. AIエージェント用ルールファイルを置く

プロジェクト直下に、AIエージェント向けのルールファイルを置きます。

例：

# AI Agent Rules

## Package Manager

- Use pnpm only.
- Do not use npm or yarn.
- Do not generate package-lock.json or yarn.lock.

## Development Flow

- Plan before implementation.
- Work in small phases.
- Add or update tests when behavior changes.
- Do not remove tests to make code pass.
- Do not modify unrelated files.

## Code Quality

- Write code that is easy for humans to read and review.
- Use clear variable, function, and class names.
- Keep functions and files small.
- Add comments for complex logic, business rules, and non-obvious decisions.
- Do not leave unclear or unexplained code.
- Avoid large, monolithic implementations.

## Architecture

- Follow DDD, Clean Architecture, or Layered Architecture where appropriate.
- Do not put business logic directly into controllers, API routes, or UI components.
- Separate domain, usecase, infrastructure, and presentation responsibilities.
- Avoid over-engineering for small learning projects, but keep responsibilities clear.

## Required Checks

Before completing a task, run:

\```bash
pnpm lint
pnpm typecheck
pnpm test:run
\```

For UI changes, also run:

\```bash
pnpm storybook:build
\```

## Git Rules

- フェーズごとに小さくcommitする
- commitメッセージは内容が分かるように書く
- commit前に差分を確認し、変更内容に対応する単体テストの作成漏れがないか確認する
- テストを追加しない場合は、その理由を説明する
- 人間の確認なしにpushしない

## Documentation

- Keep README.md updated.
- Keep docs/roadmap.md updated.
- Record important technical decisions.

AIに毎回同じことを口頭で説明するのではなく、ファイルとしてルール化しておくのが重要です。

17. ある程度進んだら、確認プロンプトの許可範囲を見直す

Claude Code で開発を進めていると、以下のような確認プロンプトが頻繁に表示されることがあります。

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again for similar commands in C:\claude\dbboard
  3. No

最初は安全のために毎回 1. Yes を選択してもよいですが、プロジェクトがある程度進み、ルールや禁止事項が固まってきたら、確認プロンプトの許可範囲を見直します。

AIエージェント開発では、確認プロンプトのたびに作業が止まると、人間側がボトルネックになります。

そのため、以下のようにAIエージェント自身に確認プロンプトの内容を精査させます。

一点、確認をします。

このPJTを円滑に進めるために、

Do you want to proceed?
❯ 1. Yes
  2. Yes, and don't ask again for similar commands in this project
  3. No

といった確認では、可能であれば `2` を選択して確認回数を減らしたいと考えています。

これまでの許可確認の中で、毎回 `1` を選んでいるために作業停止が多い確認があれば洗い出してください。

そのうえで、以下の観点で分類してください。

- `2` を押してよい可能性が高い確認
- `1` のままにすべき確認
- 人間確認が必要な確認
- `No` を選ぶべき確認

`2` を押してよい可能性が高いものについては、対象コマンド、判断理由、影響範囲を整理して許可申請してください。
こちらで内容を確認し、問題なければ `2` を押下します。

まとめ

AIエージェント開発では、AIにどれだけ自由に作らせるかよりも、壊さない仕組みを最初に作ることが重要です。

自分が現時点で重要だと感じている初期設定は以下です。

  • everything-claude-code を参考にする
  • awesome-design-md / DESIGN.md を使う
  • モダンだが実務的な技術選定にする
  • pnpmを使う
  • AIまわりの情報収集を継続する
  • TDDを前提にする
  • 人間が読みやすいコードと、意図が分かるコメントを重視する
  • DDDやClean Architectureを参考に、責務を分けた設計にする
  • pre-commit / pre-push を設定する
  • commit前に、変更内容に対応する単体テストの作成漏れがないか確認する
  • commitはAI、pushは人間にする
  • ローカル開発環境を整える
  • 最初に /plan でロードマップを作る
  • ヘルプ・マニュアルはClaudeに任せる
  • claude.md や .claude に進捗を管理させる
  • READMEやdocsを常に最新にする
  • AIエージェント用ルールファイルを置く
  • ある程度進んだら、確認プロンプトの許可範囲を見直す

AIエージェントは、非常に速く実装できます。
しかし、速く作れるからこそ、テスト・ルール・ドキュメント・フェーズ管理が必要です。

今後も、自分のプロジェクトで得た知見を追記していきます。
そしてこの記事をAIエージェントに読ませるだけでベースのルールを理解して開始することができます。

Discussion