はじめに
コーディングエージェントを使った開発は速いです。「認証を実装したい」と伝えれば、ファイル構成の提案から実装・テストまであっという間に進みます。
ただ、速い分だけ「なぜその設計にしたか」「どのトレードオフを選んだか」が記録に残りにくいです。人間同士のレビューなら口頭でも補完できますが、エージェントとのやりとりはセッションをまたぐと基本的にリセットされます。前回の判断の根拠を次のセッションでも引き継いでもらうには、何かしら明示的な仕組みが必要です。
そこで試みたのが、エージェントに作業ログを自動生成させる運用です。運用してみてわかったことをまとめます。
運用の全体像
ドキュメントは3層に分けて管理しています。
docs/
instructions/ # セッション作業ログ（日付ベース）
20260324.md
20260409.md
20260430.md
...
feature/ # フィーチャードキュメント（ブランチベース）
add_oauth/
testcase.md # テストケース仕様書
testcode.md # テストコード実装記録
add_passkey/
testcase.md
testcode.md
AGENTS.md # エージェントへの指示ファイル
| 層 | 対象 | 更新タイミング |
|---|---|---|
AGENTS.md |
エージェントへの恒久的な指示 | プロジェクト設計が変わったとき |
docs/instructions/ |
セッション単位の作業ログ | 実装・修正が完了するたび |
docs/feature/ |
フィーチャー単位のテスト仕様 | テストケース作成・実装時 |
層1：エージェントへの指示ファイル（AGENTS.md）
AGENTS.md はエージェントが最初に読むルールファイルです。このプロジェクトでは、使用している Next.js のバージョンに独自の破壊的変更があったため、次のような指示を入れています。
# This is NOT the Next.js you know
This version has breaking changes — APIs, conventions, and file structure
may all differ from your training data. Read the relevant guide in
`node_modules/next/dist/docs/` before writing any code.
Heed deprecation notices.
「トレーニングデータの知識に頼らず、必ずプロジェクト内のドキュメントを読め」という指示です。コード生成の前に実際の仕様を確認させることで、古い API パターンで実装されるリスクを減らせます。
ここに書くのは「毎回言わなくてもよいようにしたい指示」だけです。一度だけ伝えれば十分なプロジェクト固有の制約や慣習をまとめておきます。
層2：セッション作業ログ（docs/instructions/YYYYMMDD.md）
実装・修正が完了するたびに、エージェントに docs/instructions/ へログを書かせます。
フォーマット
各ログは次の構成を基本としています。
# 作業ログ YYYY-MM-DD
## 1. <機能名 or 修正内容>
### 概要
何を実装・修正したか（1〜3行）
### 実装内容
実装したファイルと内容の一覧（表形式）
### 実装のポイント
設計上の判断・選択肢のトレードオフ・ハマりポイント
実際のログの例（抜粋）
# 作業ログ 2026-04-30
## OAuth 2.1 Authorization Code + PKCE の実装
### 概要
外部クライアントからスコープベースのサービス一覧 API を利用できるようにした。
スコープは `services:view`（閲覧）と `services:edit`（操作）を個別に認可できる。
### 実装のポイント
**アクセストークンとセッショントークンの区別**
`typ: "at+JWT"` クレームを付与することで、既存のセッショントークンを
OAuth API に流用できないようにした（RFC 9068 準拠）。
**発生した問題と対処**
| 問題 | 対処 |
|---|---|
| PKCE code_verifier の生成コマンドで `tr -d` を使ったため文字数が不足 | `tr '+/' '-_'` に変更し文字数を保つように修正 |
| Admin ユーザで権限リストが空配列になる | DB ではなく ECS から直接クエリするよう修正 |
「何を実装したか」よりも「なぜそうしたか」「どこでハマったか」を中心に書かせています。実装内容はコードやコミット履歴から読めますが、判断の背景は残らないためです。
セッションをまたぐ判断の引き継ぎ
このログが最も役立つのは、複数セッションにわたる機能開発です。
たとえばパスキー認証の実装では、最初のセッションで「identifier-first（loginId を入力してからパスキー認証）」という設計を選びました。ところが次のセッションで「discoverable credentials（OS のパスキーピッカーで直接認証）」に変更することになりました。
変更の経緯がログに残っていれば、次のセッションで「なぜ変更したか」を改めて説明する必要がありません。
## discoverable credentials への変更（identifier-first からの移行）
### 変更の背景
identifier-first 方式ではユーザが loginId を入力すると、サーバが
`allowCredentials` を構築して返す。discoverable credentials 方式では
`allowCredentials` を渡さず、OS のパスキーピッカーが起動する。
ユーザの特定は verify 後に credentialId から行う。
ログに誤りがあった場合の修正
ログに誤った内容が記録されていた場合、元のログは書き換えず、後続のログに訂正セクションを追記する方針をとっています。
ログは「そのセッション時点での認識」の記録です。後から書き換えると「なぜ判断が変わったか」の経緯が失われるためです。
訂正の書き方
## [訂正] OAuth スコープ設計の修正
### 訂正対象
2026-04-30 のログ「OAuth 2.1 Authorization Code + PKCE の実装」
### 内容
前回のログでは `services:view` スコープで一覧取得と詳細取得の両方を許可すると記録したが、
設計を見直した結果、詳細取得には `services:detail` を別途要求することにした。
### 変更前 → 変更後
| 操作 | 変更前スコープ | 変更後スコープ |
|---|---|---|
| 一覧取得 | services:view | services:view |
| 詳細取得 | services:view | services:detail |
エージェントへの文脈補正
誤ったログが残っている状態で新しいセッションを始めると、エージェントはその誤りを正として読みます。セッション冒頭で明示的に補正するか、訂正をログ内に残しておくことが重要です。
○○日のログに誤りがあります。
services:view の設計について、詳細取得には services:detail が必要に変更されました。
○○日のログに訂正を追記してください。
エージェントに訂正を追記させることで、以降のセッションでは正しい文脈を引き継がせられます。
層3：フィーチャードキュメント（docs/feature/<ブランチ名>/）
テストに関してはブランチ単位でドキュメントを分けています。ファイルは2種類です。
testcase.md — テストケース仕様書
テストケースを it.todo として書いた時点でエージェントに生成させます。実装前の「何をテストするか」の合意として使います。
# テストケース一覧 — feature/add_oauth
## resolve-caller.test.ts（22件）
### resolveFromBearer
| # | テストケース名 |
|---|---|
| 1 | Authorization ヘッダーが null のとき null を返すこと |
| 2 | Authorization ヘッダーが undefined のとき null を返すこと |
| 6 | 有効なアクセストークンを渡すと userId が含まれる結果を返すこと |
| 9 | 有効期限切れのアクセストークンを渡すとエラーをスローすること |
| 12 | Basic スキームで有効なアクセストークン文字列を渡しても null を返すこと |
コードレビュー時に「このケースは考慮されているか」を確認するのに使えます。テストコードを読まなくても仕様の範囲が一覧で把握できます。
testcode.md — テストコード実装記録
it.todo を実際のテストコードに変換した後でエージェントに生成させます。実装したファイル・ケース数・テスト結果をまとめます。
# テストコード実装記録 — feature/add_oauth
## 実装ファイル一覧
| ファイル | ケース数 | 種別 |
|---|---|---|
| __tests__/oauth/pkce.test.ts | 17 | 純粋関数 |
| __tests__/oauth/scope.test.ts | 25 | 純粋関数 |
| __tests__/oauth/token.test.ts | 24 | 純粋関数 |
| __tests__/oauth/authorization-code.test.ts | 14 | DB 統合テスト |
## テスト実行結果
Test Files 20 passed (20)
Tests 516 passed | 1 skipped (517)
PR レビュー時に「テストは通っているか・どの層のテストが何件あるか」を一目で確認できます。
運用して気づいたこと
よかったこと
「なぜ」が残る
コミットメッセージや PR 説明は「何をしたか」に偏りがちです。作業ログは「なぜその設計にしたか」「どの選択肢を捨てたか」を自然に含む形式になっています。数ヶ月後に同じ箇所を触るとき、ログがあると判断を再現しやすいです。
ハマりポイントが資産になる
エージェントはハマった問題と対処をそのままログに書いてくれます。同じ問題に次のセッションで再遭遇したとき、ログを参照すれば同じ調査をやり直さずに済みます。この記事の「Next.js 15 の罠2選」も、作業ログを読み返してネタを見つけました。
テスト仕様と実装の乖離を防ぐ
testcase.md を実装前に出力させる習慣によって、「テストケースの設計」と「コードの実装」が別のフェーズとして分離されます。実装しながらテストを考えると見落としやすいケースが、事前に一覧化することで明確になります。
注意点
ログの質はプロンプトの質に依存する
「作業ログを書いて」とだけ伝えると薄い内容になります。「問題・原因・対処の形式で、設計判断の理由を含めて書いて」のように形式と重点を指示する必要があります。
更新を忘れると一気に陳腐化する
数セッション分のログが抜けると、前後のつながりが失われます。「実装が終わったらログを書く」をセッション終了の条件に組み込むことが重要です。
まとめ
コーディングエージェントとの開発でドキュメントを自動生成する運用をまとめると、次のようになります。
| ファイル | 目的 | 更新タイミング |
|---|---|---|
AGENTS.md |
エージェントへの恒久的な指示 | プロジェクト方針が変わったとき |
docs/instructions/YYYYMMDD.md |
判断・設計・ハマりの記録 | セッション完了ごと |
docs/feature/<branch>/testcase.md |
テスト仕様（実装前） | テストケース（it.todo）作成時 |
docs/feature/<branch>/testcode.md |
テスト実装記録（実装後） | テストコード実装完了時 |
エージェントが速く実装してくれる分、「なぜその判断をしたか」は意識して残しにいかないと消えていきます。ログ生成を運用の一部に組み込むことで、スピードを落とさずに判断の文脈を蓄積できるようになりました。