最近、新しいシステムをゼロから作る機会があった。せっかくなので、Claude CodeなどのAIコーディングエージェントを遠慮なくこき使いながら進めている。

コードを書く速度は、笑ってしまうほど上がった。以前なら数日かかった実装が、昼食から戻るころには形になっている。ところが、作業を進めるうちに妙な居心地の悪さを覚えるようになった。AIにコードを書かせる前に、人間が決めておくべきことがあるのではないか。

たとえばディレクトリ構成、APIの設計、エラーレスポンスの形式である。ここを決めずに任せると、AIはその時点でもっとも合理的に見える実装を選ぶ。それ自体は悪くない。ただ、別の日に同じ指示を出しても、同じ構成になる保証はどこにもない。Claude CodeからCodexに乗り換えれば、なおさらだ。

喩えるなら、毎日違う大工がやってくる現場である。どの大工も腕はいい。しかし設計図がなければ、月曜の大工は和室を作り、火曜の大工はその隣に吹き抜けを拵える。1部屋ずつ見れば立派でも、家としては支離滅裂になる。実装するAIが変わるたびに設計が変わるようでは、長く保守できるはずがない。

そこで、新規開発の最初に決めておきたいことを書き出してみた。断っておくと、すべてのプロジェクトが同じ技術を使うべきだという話ではない。大事なのは判断の基準をはっきりさせ、それを守り続けられる仕組みを作ることだと僕は考えている。

同じ敷地に建てる

まず、複数のアプリケーションを作るなら、モノレポにしたい。構成はたとえば次のようになる。

apps/
  web/              # React SPA
  admin/            # 管理画面
  api/              # Go API
  docs/             # Docusaurus
packages/
  api-client/       # OpenAPIから生成するクライアント
  shared/           # 共通ライブラリ

フロントエンドもバックエンドもドキュメントも、同じリポジトリに置く。コードを共有しやすく、変更をまとめてレビューできるのは、昔からよく言われる利点だ。AIと開発するなら、関連する仕様と実装を同じワークスペースで見渡せることも効いてくる。APIの仕様を変えたとき、OpenAPI、バックエンド、フロントエンドの型定義を1度に直せるのは、地味にありがたい。

もっとも、モノレポにしただけで設計が勝手に整うわけではない。同じ敷地に建てても、どの棟がどの棟に寄りかかってよいかは別の話である。アプリケーション同士の依存関係や、共通パッケージの責務には、別途ルールが要る。

契約書はOpenAPIに一本化する

フロントエンドとバックエンドを分けて作る場合、APIの型を二重に管理するのは御免蒙りたい。そこで、OpenAPIをAPI契約の正本として扱う。OpenAPIの定義から、次のものを生成する。

  • Goのリクエスト・レスポンス型
  • Goのサーバーインターフェース
  • TypeScriptの型定義
  • フロントエンド用のAPIクライアント
道具としては、Goならoapi-codegen、TypeScriptならopenapi-typescriptあたりが候補になる。これで、フロントとバックがそれぞれ勝手に型を書く必要はなくなる。

ただ、本当にうれしいのは生成そのものではない。APIの仕様変更は必ずOpenAPIから始めるという開発ルールを置けることだ。AIにAPIを足してもらうときも、まずOpenAPIを書き換え、その定義に従って実装させる。大工に口頭で指示するのをやめ、図面を先に直す習慣である。

とはいえ、型を生成しただけで、実装との整合性が保証されるわけではない。リクエスト・レスポンスの検証も、契約テストも必要になる。いずれはCIでOpenAPIの破壊的変更も検出できるようにしたい。

失敗の返し方を揃える

APIで意外と後回しにされがちなのが、エラーレスポンスだ。何も決めずに作ると、エンドポイントごとに違う形式のエラーが生えてくる。

{"error": "Not Found"}
{"message": "Resource not found", "code": 404}

どちらも意味は通じる。しかし、その違いを吸収させられるのはフロントエンドである。そこで、RFC 9457(Problem Details for HTTP APIs)を採用する。

{
  "type": "https://example.com/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "指定されたリソースは存在しません"
}
Content-Typeにはapplication/problem+jsonを使う。これでAPI全体のエラー形式が揃う。独自のエラー形式をゼロから設計しなくて済むのも、なにげに大きい。

間取りをファイルで決める

今回、個人的にいちばん効いたと感じたのがファイルベースルーティングである。React SPAでは、ルーティングをコードで直接定義するやり方もある。一方、TanStack Routerのように、ファイルベースルーティングを使えるライブラリもある。

routes/
  index.tsx
  login.tsx
  users/
    index.tsx
    $userId.tsx
  settings/
    index.tsx

ファイルの構成とURLの構造を対応させておけば、新しい画面をどこに置くべきかで迷わない。間取り図がそのまま床に描いてあるようなものだ。

実は、AIにファイルベースルーティングを提案したところ、「現時点では画面数が少ないため、メリットが小さい」と返された。確かに、今の画面数だけを見れば、その判断には理がある。

しかし、僕が気にしているのは今の実装コストだけではない。今後どのAIが新しい画面を足しても、同じ構成になることだ。

というのも、過去にAIへページの追加を頼んだら、そのページがしれっとcomponentsディレクトリの中に作られていたことがあるからだ。画面をどこに置くかの規則がなかったので、AIはその場でいちばん筋が通りそうな置き場所を選んだのだろう。居間を頼んだのに、大工が物置の中に拵えていったようなものである。開発が進んでからルーティングを組み替えるより、最初に規則を敷いておく方がいい。そう判断した。

むろん、ファイルベースルーティングですべての責務が片づくわけではない。画面、コンポーネント、ビジネスロジック、APIアクセスの責務をどう分けるかも、あわせて決めておきたい。

意識しなくても守られる仕組み

ここからは、ルールを守らせる側の話になる。

ESLint、Prettier、TypeScriptの型チェックは、今やAIがプロジェクトを作るときに勝手に設定してくれることも多い。導入の手間は、以前ほどかからなくなった。ただ、肝心なのはツールがあることではない。開発者もAIも、意識しなくてもルールに従ってしまう状態を作ることだ。標準にしたいのは次のあたりである。

  • ESLintによるコードチェック
  • Prettierによるフォーマット
  • TypeScriptのstrict設定
  • CIでのLint・型チェック
  • フォーマットルールの統一

もっとも、ESLintとPrettierは今回AIが気を利かせて勝手に入れてくれたものだ。最近はRust製のOxlintやOxfmtという選択肢もあり、こちらの方がパフォーマンスは断然いい。以前、別のプロジェクトで移行したときは、Lintが約37倍、フォーマットが約91倍速くなった(ESLintとPrettierをOxlint・Oxfmtに移行した話)。チェックを頻繁に回すのなら、待ち時間は短いに越したことはない。

必要なら、ディレクトリ間の依存関係も縛る。検証にはdependency-cruiserなどが使える。AIに「このディレクトリからはimportしないで」と頼むだけでなく、破ったら機械が気づく状態にしておきたい。大工への申し送りより、物理的に通れない壁の方がよほど確実である。

チェックを手で実行する運用は、早晩どこかで漏れる。そこでHuskyを入れ、Git Hooksで自動化する。役割分担はたとえば次のようになる。

タイミング実行内容
pre-commitlint-stagedによるLint・Format
commit-msgcommitlint
pre-push型チェック・Unit Test
Pull RequestLint・型チェック・各種テスト

すべてのテストをPush前に走らせると、開発の足が止まる。重いIntegration TestやE2EはCIに回す。それに、Git Hooksはその気になれば回避できる。最後の砦は、やはりCIで強制するしかない。

コミットメッセージも揃えておく。採用するのはConventional Commitsだ。

feat(auth): add Google login
fix(api): handle validation errors
docs(adr): document API design
refactor(web): simplify user form
test(api): add integration tests

Huskyとcommitlintを組み合わせれば、形式から外れたコミットを弾ける。これまでコミットメッセージは、書く人によって流儀がばらばらになりがちだった。AIがコミットまで作るのなら、形式を揃える意味はなおさら大きい。履歴を使ってCHANGELOGを生成したり、リリース管理に応用したりもできる。

散らかった端材を片づける

AIとの開発で気になるのが、不要なコードの堆積である。AIは機能を足すことには熱心だが、リファクタリングで用済みになったファイルや関数まで律儀に片づけてくれるとは限らない。大工は新しい棚を作るのは早いのに、古い棚を捨てていかないのだ。

そこでKnipを入れる。Knipが検出してくれるのは、主に次のものだ。

  • 未使用のファイル
  • 未使用のexport
  • 未使用の依存ライブラリ
  • 宣言されていない依存関係

殊にモノレポでは、使われなくなった共通コードやパッケージが残りやすい。ただし、ファイルベースルーティングやコード生成のように、静的な参照だけでは判断できない仕組みもある。設定の調整は避けられない。個人的には、Knipは毎回のコミットで走らせるより、CIや定期的なメンテナンスで回すくらいがちょうどいいと思っている。

テストは量より粒度

AIに「テストを書いて」と頼むと、山のようなテストコードが返ってくることがある。だが、テストが多いことと品質が高いことは、必ずしも一致しない。内部の関数の呼び出し回数や、単純なgetterの動作ばかり確かめても、肝心の業務仕様の不具合が防げるとは限らないのである。

だから、テストの粒度を最初に決めておきたい。

種類主な対象
Unit Testビジネスロジック、計算、バリデーション
Integration TestDBアクセス、API、認証・認可
Contract TestOpenAPIとAPI実装の整合性
E2E Test重要なユーザーフロー

APIの処理を足したらIntegration Testを書く。業務ロジックを足したらUnit Testを書く。ユーザーが触る重要な機能なら、E2Eも検討する。変更の中身を見れば、どのテストが要るのか判断できる状態にしておきたいわけだ。

カバレッジの数字を目標にするのではなく、重要な仕様や境界条件が検証されていることを重視する。それから、バグを直したら同じ問題が再発しないよう、回帰テストを足すルールも必要になる。

事故のあとに読む日誌

新規開発で忘れられがちなのが、ログである。開発中はまず動かすことが優先され、障害調査に必要な情報の設計は後回しになりやすい。しかし、本番で問題が起きてからログを足すのでは遅い。最低限、次のことは最初に決めておきたい。

  • JSON形式の構造化ログ
  • INFO・WARN・ERRORなどの使い分け
  • リクエストIDによる処理の追跡
  • エラー発生時の原因や処理対象の記録
  • 個人情報やSecretを出力しないルール
  • ログの保存期間と監視方針
Goなら、標準ライブラリのslogが使える。
logger.Error(
    "failed to create user",
    "request_id", requestID,
    "error", err,
)

大事なのは、エラーが起きたときに何があったのかを後から辿れることだ。リクエストIDをAPI全体で引き回しておけば、複数の処理にまたがる障害も追いやすくなる。ログを入れるかどうかをAIの気分に任せず、どの処理で何を記録するかを最初に決めておきたい。

図面と、図面を引いた理由

仕様書や設計資料も、最初から管理しておきたい。今回はDocusaurusを使う方針にした。ドキュメントはモノレポの中に置き、実装と一緒にGitで管理する。

apps/docs/
  docs/
    architecture/
    api/
    development/
    adr/

こうしておけば、開発者はドキュメントサイトで仕様を確認できる。一方、Claude CodeやCodexのようなAIは、リポジトリ内のMarkdownをそのまま読める。つまり、人間とAIが同じ図面を見ているわけだ。ドキュメントがコードと別の場所にあると、更新を忘れて中身がずれていく。仕様の変更とドキュメントの更新は、できる限り同じPull Requestで済ませたい。

できあがったドキュメントは、Cloudflare Pagesなどでホスティングする。Cloudflareの無料枠を使えば、小規模なプロジェクトならコストはほとんどかからない。さらにCloudflare Accessを組み合わせれば、認証付きのドキュメントサイトになる。Google Workspaceのメールドメインや、許可したメールアドレスだけにアクセスを絞れるので、認証の仕組みを自前で作らなくて済む。

ただし、@gmail.com全体を許可するのは、いくらなんでも門が広すぎる。メールアドレスや組織のドメインなど、適切な条件を設定する必要がある。無料枠の人数や利用制限も、事前に確かめておきたい。

技術選定の記録も残す。なぜGoにしたのか。なぜReact SPAにしたのか。なぜGinのようなWebフレームワークを入れなかったのか。こうした判断を後から振り返るために、ADR(Architecture Decision Record)を書く。

adr/
  0001-use-monorepo.md
  0002-use-openapi.md
  0003-standardize-api-errors.md
  0004-use-file-based-routing.md

ADRには、次の3つを記録する。

  • Context:なぜ検討が必要になったか
  • Decision:何を採用したか
  • Consequences:どのような影響があるか

この仕組みは、AIとの開発でこそ効く。AIは過去の議論を知らなければ、とっくに検討を終えた技術を性懲りもなく再提案してくる。新しく来た大工が「ここ、吹き抜けにしませんか」と言い出すのと同じだ。ADRがあれば、判断の背景をその場で確かめられる。採用した理由だけでなく、採用しなかった理由も書いておくことが大事だと思う。

大工への申し送り

ここまで決めたルールは、AIが読める場所に置いておく。そのためにAGENTS.mdやCLAUDE.mdを使う。中身はたとえばこんな具合だ。
# Development Rules

## API
- OpenAPIをAPI契約の正本とする
- APIの追加・変更時はOpenAPIを先に更新する
- エラーはRFC 9457に従う

## Frontend
- ファイルベースルーティングを使用する
- APIクライアントは生成されたものを使用する

## Testing
- ビジネスロジックにはUnit Testを追加する
- APIの変更時はContract Testを確認する
- バグ修正時には回帰テストを追加する

## Architecture
- 既存のADRを確認する
- 技術選定を変更する場合はADRを更新する

もっとも、AI向けのドキュメントに書いたからといって、必ず守られるわけではない。申し送りは読み飛ばされることがある。人間でもそうなのだから、AIだけを責めるのは酷だろう。機械的に検証できるものは、LintやCIで検証する。文章による指示と、機械による制約を組み合わせることが肝心なのである。

そして、ここまで入れたツールも、実行されなければただの飾りだ。GitHub ActionsなどでPull Requestのたびに自動チェックを走らせる。構成はたとえば次のようになる。

Pull Request
    |
    +-- Lint / Format
    |
    +-- Type Check
    |
    +-- Unit Test
    |
    +-- Integration Test
    |
    +-- OpenAPI Contract Check
    |
    +-- Knip
    |
    +-- Security Scan
    |
    +-- Build
    |
    +-- E2E Test
    |
    v
  Review / Merge

必要に応じて、GitleaksなどでSecretを検出したり、Renovateで依存ライブラリを更新したりもしたい。大事なのは、AIが書いたコードも人間が書いたコードも、同じ検査を通すことだ。AIに「必ずテストを実行して」と頼むだけでなく、テストが落ちていればマージできない環境を作る。検査に通らない家は、誰が建てても引き渡さない。

建てないという設計

ここまでずいぶん色々な道具を並べたが、最初から全部入れるべきだとは思っていない。

肝心なのは、有名な技術を使うことではなく、その技術を使う理由を説明できることだ。採用しないという判断も、立派なアーキテクチャ上の意思決定である。建てなかった部屋も、図面の一部なのだ。

AIのおかげで、ソフトウェアの作り方は大きく変わりつつある。コードを書くコストは下がり、これまでにない速さで機能を足せるようになった。だが、生成されたコードの設計や品質が、勝手に揃ってくれるわけではない。長く運用するシステムなら、今の速度だけでなく、数年後に別の開発者や別のAIが手を入れる日のことも考えておく必要がある。そのために、僕は次のことを意識したい。

  1. 設計のルールを最初に決める
  2. ルールをドキュメントとして残す
  3. 可能な限りツールで自動検証する
  4. 技術選定の理由をADRに記録する
  5. AIが変わっても同じ設計方針を維持できるようにする

これからは、AIにどれだけコードを書かせられるかだけでなく、AIが品質の高いコードを書き続けられる環境をいかに作るかが問われるのだろう。

以上、日替わりの大工に家を建ててもらうための、最初の段取りの話である。腕のいい大工が毎日来てくれる時代になった。だからこそ、図面を引くのは人間の仕事として残る。AIに実装を任せるためにこそ、人間が最初に設計のルールを決めておく。 今回の新規開発を通じて、そのことを改めて思い知った次第だ。