AI を活用した開発に「いちエンジニア」が向き合い、実践している 3 つの仕組み

はじめに

こんにちは、@masa-asa です。

AI にコードを書いてもらうこと自体は、日に日に簡単になっています。一方で、業務で使おうとすると「出力をどこまで信頼するのか」「どうすればチームの方針に沿った実装になるのか」という悩みが出てきます。

私も明確な正解を持っているわけではありませんが、それでも AI をできるだけ上手に活用するために、現在は次の 3 つを実践しています。

1. CLAUDE.md や AGENTS.md にリポジトリの前提を書く
2. 技術スタックに合ったスキルを導入する
3. 設計・実装・レビューをスキルとして分ける

この記事では、それぞれに何を書き、どのように使い分けているかを紹介します。

AI の出力を「仕組み」で支える

AI と共に開発する手法として、プロンプトエンジニアリング、コンテキストエンジニアリング、ハーネスエンジニアリング、ループエンジニアリングなど、さまざまな考え方が提案されています。

• プロンプトエンジニアリング：モデルへの「指示文そのもの」を磨く技術。何をどう言えば望む出力が出るか、言葉と文章構成のレベルで最適化する。
• コンテキストエンジニアリング：指示文だけでなく、履歴・ツール出力・検索結果などモデルの限られたコンテキスト窓に「何を入れて何を捨てるか」を設計する技術。単発の言い方から「モデルが見る世界全体」の管理へ視点を広げたもの。
• ハーネスエンジニアリング：モデル本体以外のすべて——ツール、ドキュメント、アーキテクチャ制約、検証機構——を設計し、エージェントが自律的に確実に働ける「環境」を作る技術。人間の役割を「コードを書く人」から「エージェントの職場を設計する人」へ転換する発想。
• ループエンジニアリング：エージェントの基本ループ（ツールを呼んで実行）の外側に、検証・自動起動・自己改善のループを何層も積み重ねる設計技術。

呼び方や手法は変化していますが、共通しているのは、AI に単発でうまい指示を出すだけでなく、信頼できる出力を継続的に得るための仕組みを作るという点です。また、最適化の対象が、AI（LLM）単体から周辺の仕組みへ広がっていると感じます。

私も、完璧なプロンプトを目指すのではなく、AI が参照する前提と作業手順をリポジトリに置くことから始めています。

1. CLAUDE.md や AGENTS.md に前提を書く

CLAUDE.md や AGENTS.md には、AI がリポジトリで作業するときに常に参照してほしい情報を書きます。

リポジトリの目的

最初に、このリポジトリが「何をするシステム」の「どの部分」なのかを書きます。

私は、インセプションデッキのエレベーターピッチを簡略化するイメージで、次の情報を記載しています。

• どのような処理を行うのか
• 何を達成するシステムなのか
• バックエンド、フロントエンド、インフラなど、どの領域を担うのか
• Cloud Run、AWS Lambda、Azure App Service、オンプレミスなど、どこで実行されるのか

AI にコードだけを見せるのではなく、コードが存在する目的まで共有するためです。

関連リポジトリ

複数のリポジトリで一つのシステムを構成している場合は、それぞれの役割も書きます。

たとえば、バックエンドのリポジトリであれば、関連するフロントエンド、ドキュメント、インフラのリポジトリと、その役割を記載します。これにより、AI が現在のリポジトリだけで完結すると誤解するのを防ぎます。

実装方針

実装時に守ってほしい方針は、箇条書きで明示します。
例として、以下のような内容を主に記載しています。

• 開発言語とフレームワーク
• YAGNI、DRY などの原則
• 採用している設計パターン
• テスト方針
• 静的解析とフォーマットのルール

抽象的な理念だけでなく、実装時に判断できる粒度で書くことを意識しています。

ディレクトリ構成

主要なディレクトリと役割も記載します。設計パターンだけでは判断しにくい具体的な配置を示し、AI が既存の構成から外れた場所にファイルを作るのを防ぐためです。

2. 技術スタックに合ったスキルを導入する

find-skills を使い、プロジェクトで利用する技術スタックに関連したスキルを探します。スキルはプロジェクト単位で導入しています。

選ぶときは、次の順序で確認します。

1. 利用している技術やサービスの公式提供元が公開しているものか
2. プロジェクトの技術スタックに合っているか

第三者が提供するスキルの場合は、導入前に配布元と SKILL.md の内容を確認します。あわせて、スキルが実行を要求するコマンドと、skills.sh に掲載されているセキュリティ監査結果も確認します。

ただし、使っているすべての技術に対してスキルを入れるわけではなく、目的に合うものがあれば導入する、という温度感です。

3. 設計・実装・レビューを分ける

AI に設計から実装までを一度に任せず、工程ごとにスキルを分けています。各工程の目的と完了条件を明確にし、人間が途中で確認できる状態を作るためです。

設計スキル

リポジトリの設計パターンに従って設計するように指示します。具体的な実装方針は CLAUDE.md などから参照できるため、設計スキルには設計時に必要な手順や観点を記載します。

設計結果を ./.design などのディレクトリへ出力させる場合もあります。AI が設計後すぐに実装へ進むのを防ぎ、人間が設計を確認して修正できるようにするためです。

実装スキル

合意した設計に基づいて実装するように指示します。設計結果をファイルへ出力している場合は、そのファイルを参照対象として明記します。

実装後はレビュー用のスキルを呼び出し、実装を担当したエージェントとは別のエージェントにレビューさせています。レビュー結果は必ずユーザーへ出力させ、人間が確認できる状態にします。

レビュースキル

レビューでは、主に次の項目を確認します。

• 設計パターンに従っているか
• 必要なテストが実装され、通過しているか
• 静的解析とフォーマットチェックに合格しているか
• 指定した分類に従って指摘しているか

レビューの分類は多様な考え方があり、確定したフォーマットがないと思われますが、私は次のように定義することが多いです。

分類	対象
critical	バグやセキュリティ上の問題など、必ず修正すべき指摘
major	設計上の問題、パフォーマンス低下、仕様とのずれなど、修正を推奨する指摘
minor	可読性や命名など、動作には影響しない任意の改善
suggestion	よりよい代替案や学習のための参考情報

設計で一度止め、人間の違和感を放置しない

AI が作成した設計は、そのまま実装へ進めずに一度止めます。ここで人間が設計をレビューし、必要に応じて添削します。

レビュー中に「なぜこの技術を選ぶのか」「この設計で本当に問題ないのか」と疑問に思ったことは、曖昧なまま放置しません。AI に質問してもよいですし、先輩や同僚に相談してもよいと考えています。重要なのは、疑問を解消してから次の工程へ進むことです。

AI に質問する場合は、Web 検索を行い、回答の根拠となる出典を明記するように指示します。ただし、AI が提示した出典が正しいとは限りません。リンク先を自分で開き、出典の内容と AI の回答が一致していることまで確認します。

AI に設計を任せることで、従来よりもかなり高速に作業を進めることができます。しかし、最終的に設計を承認し、実装へ進めるかを判断するのは人間という方針を採っています。

まとめ

AI を用いた開発をカオスにしないために、私は次の 3 つを実践しています。

1. CLAUDE.md や AGENTS.md でリポジトリの前提を共有する
2. 技術スタックに合ったスキルで知識を補う
3. 設計・実装・レビューをスキルとして分ける

AI への指示を一度で完成させるのではなく、前提と手順をリポジトリに蓄積し、出力を確認しながら改善しています。

この記事で紹介した内容は、AI を活用した開発の最新動向を網羅したものではありません。また、工程ごとに人間の確認を挟むため、最速の方法でもありません。それでも、一人のエンジニアとして AI に向き合い、自分で内容を理解し、他者に説明できる状態を保ちながら開発を進めるために、現時点ではこの方法を実践しています。この実践例が、読者の参考になれば幸いです。

今後も新しい方法を学び、実際に試しながら、この仕組みを改善していきたいと思います。

付録

最後に、今回の記事の内容と私が使っているものをベースに公開用として
AGENTS.md（CLAUDE.md）と設計・実装・レビューのスキルを記載します。
プロジェクト名、リソース名などは架空の内容へ置き換えています。そのままコピーして使う完成形ではなく、何をどの程度具体的に書くかの参考としてご活用いただけると幸いです。

AGENTS.md（CLAUDE.md）の例

# リポジトリの説明

このリポジトリは、架空のイベント予約サービスのフロントエンドです。

ユーザーがイベントを検索し、開催日時や会場を確認して予約するための画面を提供します。予約データはバックエンドの API から取得し、このリポジトリからデータベースへ直接アクセスしません。

このリポジトリは Next.js で実装し、フロントエンド用のホスティング環境へデプロイします。

# 関連リポジトリ

## `example-event-api`

イベントの検索、予約、キャンセルを扱うバックエンド API です。データベースへのアクセスとドメインロジックは、バックエンド側が担当します。

## `example-docs`

システム全体の設計資料、用語集、運用手順を管理するリポジトリです。

# このリポジトリの実装方針

- TypeScript で実装する
- Next.js の App Router を使用する
- バックエンドとの通信には、生成済みの API クライアントを使用する
- このリポジトリからデータベースへ直接アクセスしない
- YAGNI、DRY の原則を基本とし、必要になる前の抽象化を避ける
- 機能単位の構成には Bulletproof React の考え方を適用する
- E2E テストは `e2e/` に配置する
- 単体テストは対象ファイルと同じディレクトリに配置する
- テストには Vitest を使用する
- E2E テストには Playwright を使用する
- 認証情報や接続文字列をコードへ記載しない

# ディレクトリ構成

```text
example-web-app/
├── src/
│   ├── app/                         # ルーティングとページの組み立て
│   │   ├── (protected)/             # 認証が必要なページ
│   │   │   └── events/
│   │   │       └── page.tsx
│   │   ├── layout.tsx
│   │   └── page.tsx
│   ├── features/                    # 機能単位のコード
│   │   └── events/
│   │       ├── components/          # この機能専用の UI
│   │       ├── hooks/               # クライアント側の状態管理
│   │       ├── api/                 # バックエンド API の呼び出し
│   │       ├── types/               # この機能で使う型
│   │       ├── utils/               # この機能専用の純粋関数
│   │       └── index.ts             # 外部へ公開する要素
│   ├── components/
│   │   ├── ui/                      # 複数機能で使う UI
│   │   └── layout/                  # 共通レイアウト
│   └── lib/                         # 全機能で使うクライアントと純粋関数
│       └── apiClient.ts             # API クライアントの共通設定
├── e2e/
└── public/
```

# 各ディレクトリの役割

## `src/app/`

Next.js App Router のルーティングとページの組み立てを担当します。

`page.tsx` は Server Component とし、`features/<機能名>/api/` からデータを取得して、型付きの props として UI コンポーネントへ渡します。データ取得の詳細や画面固有のロジックを `page.tsx` に直接実装しません。

## `src/features/`

画面やユースケースごとにコードをまとめます。新しい機能を追加するときは、原則として最初に `features/` 配下へフォルダーを作成します。

| サブディレクトリ | 配置するもの |
| --- | --- |
| `components/` | その機能だけで使う UI コンポーネント |
| `hooks/` | フィルターなど、クライアント側の状態管理 |
| `api/` | バックエンド API の呼び出し |
| `types/` | サーバーとクライアントで共有する型 |
| `utils/` | その機能だけで使う純粋関数 |
| `index.ts` | 機能の外部へ公開する要素 |

### 依存関係のルール

- feature 間で直接 import しない
- 複数の feature で必要になった UI は `src/components/` へ移動する
- 複数の feature で必要になった処理は `src/lib/` へ移動する
- サーバー専用の API クライアントを Client Component から import しない
- バックエンド API の URL や認証設定は `src/lib/apiClient.ts` で一元管理する

## `src/components/`

複数の feature で使用する UI コンポーネントだけを配置します。最初から共通化せず、同じ役割のコンポーネントが二つ以上の機能で必要になった時点で移動します。

## `src/lib/`

全機能で使用する API クライアントの設定と、特定の機能に依存しない純粋関数を配置します。

# ファイルの配置ルール

新しいファイルは、次の基準で配置します。

1. 一つの機能だけで使う UI は `src/features/<機能名>/components/` に置く
2. クライアント側の状態管理は `src/features/<機能名>/hooks/` に置く
3. バックエンド API の呼び出しは `src/features/<機能名>/api/` に置く
4. 複数の機能で使う UI は `src/components/` に置く
5. 複数の機能で使う処理は `src/lib/` に置く

判断できない場合は、実装を始める前にユーザーへ確認してください。

# 命名規則

- React コンポーネントのファイル名は PascalCase にする
- それ以外の TypeScript ファイルは camelCase にする
- テストファイルは対象ファイル名に `.test` を付ける
- 略語よりも役割が伝わる名前を優先する

# テスト方針

- 変更したビジネスロジックには単体テストを追加する
- 不具合を修正するときは、修正前に再現テストを追加する
- ユーザーの主要な操作は E2E テストで確認する
- バックエンド API に依存するテストでは、依存先をモックするか結合テストであることを明示する

# 禁止事項

- 認証情報、個人情報、接続文字列をコードやログへ出力しない
- ユーザーの承認なしに依存パッケージを追加しない
- 関係のないファイルを変更しない
- 既存のテストを理由なく削除または無効化しない

この例では、AGENTS.md や CLAUDE.md に、リポジトリの目的、関連リポジトリ、技術スタック、ディレクトリの責務など、工程によらず参照する前提だけを記載しています。

工程別スキルの例

設計で一度停止する手順やレビューの観点は、特定の工程でだけ必要になる情報です。そのため、私は次のようにスキルへ分けます。

設計スキル

---
name: design
description: ユーザーから設計を依頼されたときに、実装前の設計を行う
---

# 設計

ユーザーが提示した要件と、リポジトリのコンテキストに基づいて、実装前に設計を行う。

- リポジトリで定められた設計パターンと実装方針に従う
- 使用する言語やフレームワークのベストプラクティスを考慮する
- 設計に利用できる関連スキルがある場合は参照する
- 変更内容、影響範囲、テスト方針を明記する
- 判断に必要な情報が不足している場合は、推測せずユーザーへ確認する

関連スキル：
- Skill A
- Skill B
・
・
・

技術仕様を調査する場合は Web 検索を行い、回答に出典の URL と該当箇所を記載する。公式ドキュメントなどの一次情報を優先し、出典から確認できない内容を事実として断定しない。

完成した設計は `./.design/` に Markdown ファイルとして出力する。ファイル名の先頭には、設計の順序が分かる連番を付ける。

設計ファイルを出力したら作業を停止し、人間のレビューを待つ。レビューで生じた疑問を解消し、設計が承認されるまで実装を開始しない。

実装スキル

---
name: coding
description: ユーザーから実装を依頼されたときに、承認済みの設計に基づいて実装する
---

# 実装

承認済みの設計と、リポジトリの実装方針に基づいて実装する。

- 設計に記載された範囲だけを変更する
- 使用する言語やフレームワークのベストプラクティスに従う
- 実装に利用できる関連スキルがある場合は参照する
- 変更内容に応じたテストを追加または修正する
- リポジトリで指定されたテスト、静的解析、フォーマットチェックを実行する
- 確認できなかった項目や失敗したチェックを隠さず報告する

関連スキル：
- Skill A
- Skill B
・
・
・

実装後は、実装を担当したエージェントとは別のエージェントでレビュースキルを実行する。レビュー結果はユーザーへ報告し、指摘への対応はユーザーの判断を仰ぐ。

レビュースキル

---
name: code-review
description: ユーザーからコードレビューを依頼されたときに、実装内容を検証する
---

# コードレビュー

設計、リポジトリの実装方針、使用する言語やフレームワークのベストプラクティスに基づいてレビューする。

- 実装が設計と一致しているか
- 要求された機能が正しく動作するか
- セキュリティ上の問題がないか
- 必要なテストが実装され、通過しているか
- 静的解析とフォーマットチェックに合格しているか
- 可読性と保守性を損なう実装がないか

レビューに利用できる関連スキルがある場合は参照する。

関連スキル：
- Skill A
- Skill B
・
・
・

指摘には、次の分類を一つだけ付ける。

| 分類 | 対象 |
| --- | --- |
| `critical` | バグやセキュリティ上の問題など、必ず修正すべき指摘 |
| `major` | 設計上の問題、パフォーマンス低下、仕様とのずれなど、修正を推奨する指摘 |
| `minor` | 可読性や命名など、動作には影響しない任意の改善 |
| `suggestion` | よりよい代替案や学習のための参考情報 |

指摘は重要度の高い順に、対象ファイルと該当箇所を示して報告する。問題がない場合も、その旨と確認できなかった項目を報告する。

このように分けると、AI へ常に渡す情報を絞りつつ、各工程では必要な手順を具体的に指示できます。