今回は開発の進捗としてAPIの開発について記事にしたいと思います。
API開発の実装スタイル
今回の開発ではClaude Codeを本格的に活用できるようになるためにAI実装で進めています。
そのため、まずはドキュメントをAIと壁打ちしながら作成しました。ドキュメントはプロダクトの仕様を詰めるのもそうですが、AI実装におけるガードレールとしても作成しています。
そしてそのドキュメントをもとにAIに実装させています。ドキュメントを参照するように実装しているので実装に取り掛かってからは形式的な作業のようなものなのでSKILLSとして作成しました。
今回の記事ではそちらの紹介、解説もしていきます。
ドキュメントの構成
以下がドキュメント構成の概要です。
docs/
├── README.md
│
├── api/ # API仕様書（各リソースごとにCRUD操作を定義）
│
├── architecture/ # アーキテクチャ設計
│ ├── overview.md
│ ├── auth.md
│ ├── signup.md
│ ├── data-model.md
│ ├── storage.md
│ ├── tech-stack.md
│ └── tables/ # テーブル定義
│
├── decisions/ # 設計決定記録
│
└── development/ # 開発ガイド
├── implementation-guidelines.md
├── directory.md
├── docker.md
├── testing.md
├── validation.md
├── constants.md
└── logging.md
api/ （API設計書）
エンドポイントの一覧と各エンドポイントに対するAPIの仕様書を配置しています。
architecture/ （アーキテクチャ関係ドキュメント）
認証基盤やインフラ基盤などのアーキテクチャに関係するドキュメントを配置しています。
decisions/ （設計決定記録）
AIと壁打ちをして意思決定記録（ADR）を格納しています。
development/ （開発ガイド）
実装時のガイドラインやディレクトリ構成など、実装方針のドキュメントを配置しています。
本プロジェクトで作成したSKILLS
/api-spec-review
概要
APIの仕様書をレビューさせるスキルです。 エンドポイント一覧のドキュメントを参照し、レビューするAPIの仕様書を選択します。選択したAPIの仕様書をレビューし確認事項を出力します。その後、ユーザーと壁打ちして仕様書の内容を詰めて更新します。
ポイント
選択したドキュメントを読ませた後に壁打ちを行うので、ドキュメントを読んで確認事項をリストにする部分はサブエージェントを作成しました。
必要な情報はドキュメントの確認事項だけなので、コンテキストの節約を意図してサブエージェントに切りました。
APIのドキュメントを作成する初期段階では、プロダクトの概要を決定してから暫定でリストにした程度なのでこのスキルを使用するフェーズでしっかり壁打ちを行い仕様を決定しています。
/implement-api
概要
APIを実装するスキルです。 レビューのスキルと同様に、最初にエンドポイント一覧のドキュメントを参照し、実装するAPIを選択します。選択したAPIの実装を行います。
実装のスコープ
本スキルで行う実装のスコープは以下です。
- 実装のプランニング
- テストコードの実装
- 実装
- テストの実行
- コードチェック
- レビュー
上記の通り、API丸々一本の実装に加え、テストやレビューなどもスコープに当てているのでサブエージェントをいくつか作成しています。以下で紹介します。
本スキルで稼働するサブエージェント
test-runner
テストを実行しテスト結果をレポート形式でレスポンスします。
code-checker
リントチェック、型チェックを実行します。問題がある場合は、件数と該当箇所をレスポンスします。
reviewer
ドキュメントの実装ガイドラインを参照してレビューをします。結果をレポート形式でレスポンスします。
ポイント
AI実装をするにあたり、実装方針、コードの内容は100％理解しておきたいので都度ユーザーに承認をもらうように作成しました。
ドキュメントのレビューをするスキルもそうですが、ある意味AIを信用していない作りにしています。
AIを本格的に使った実装が初めてなので、自分が作成したドキュメントがAIが自律的に実装をする上で必要な情報を揃えられているか、整備できているかを確認する手段にもなると考えています。
まとめ
AI駆動開発に入門しましたが、まだまだ手探り状態です。それでもドキュメントをリポジトリの中で固めてみたりSKILLSを作ってみたりと新しいことに挑戦してみると視野が広がります。
Claude Codeに関する情報を日々キャッチアップして、実装を進めながら自分なりに上手く使いこなせるようになっていきたいと思います。
