← Agent-First Development

チームワークフロー

はじめに

Agent-First Development はツールの使い方だけの話ではない。チームの働き方そのものが変わる。PR のサイズ感、ブランチ戦略、知識共有の方法、生産性の測り方。すべてを再考する必要がある。

本モジュールでは、エージェントを活用するチームのワークフローを具体的に設計する。

High-Throughput Merge: 高速マージの哲学

従来のモデルの限界

従来:
  大きな PR → 詳細レビュー → 修正依頼 → 再レビュー → Approve → マージ
  期間: 数日〜1 週間

問題:
  - マージまでの時間が長い
  - コンフリクトが増える
  - レビュアーの負担が大きい
  - フィードバックループが遅い

Agent-First モデル

Agent-First:
  小さな PR → 自動チェック + 軽いレビュー → マージ → follow-up PR で改善
  期間: 数時間

原則:
  - 小さく、頻繁にマージする
  - 完璧を求めず、改善を継続する
  - blocking より follow-up

Short-lived PR の実践

目安:

  • 変更ファイル数: 1-5 ファイル
  • 変更行数: 50-200 行
  • レビュー時間: 15-30 分
  • PR の寿命: 当日〜翌日マージ

大きな機能の分割例:

機能: 患者検索 API の実装

従来: 1 つの大きな PR
  → 15 ファイル変更、500 行追加

Agent-First: 5 つの小さな PR
  PR 1: domain model の定義 (2 ファイル, 60 行)
  PR 2: repository interface + 実装 (3 ファイル, 120 行)
  PR 3: API handler (2 ファイル, 80 行)
  PR 4: テスト (3 ファイル, 150 行)
  PR 5: ドキュメント更新 (2 ファイル, 40 行)

Follow-up over Blocking

従来:
  レビュアー: 「この変数名は patientName の方がいい」
  → PR がブロックされる → 修正 → 再レビュー

Agent-First:
  レビュアー: 「命名を改善する follow-up PR を作ってもらえますか？」
  → 現在の PR はマージ → follow-up PR で改善
  （または、エージェントに follow-up PR を依頼）

Blocking が正当化される場合:

  • セキュリティ上の問題
  • データ破損のリスク
  • Golden Principles への違反
  • ビジネスロジックの明確な誤り

Follow-up で十分な場合:

  • 命名の改善
  • コメントの追加
  • テストケースの追加
  • リファクタリング

ブランチ戦略

エージェント作業用のブランチ

main
  ├── feature/patient-search      ← 人間が設計、エージェントが実装
  ├── feature/notification-system  ← 別のエージェントが並列作業
  ├── fix/error-handling           ← エージェントによるクリーンアップ
  └── chore/doc-update            ← エージェントによるドキュメント更新

Worktree を使った並列作業

# ブランチごとに worktree を作成
git worktree add ../raica-patient-search feature/patient-search
git worktree add ../raica-notification feature/notification-system

# 各 worktree で独立したエージェントを実行
# → 互いに干渉しない

命名規則

feature/xxx  - 新機能
fix/xxx      - バグ修正
chore/xxx    - クリーンアップ、ドキュメント更新
agent/xxx    - エージェントが自律的に作成した PR（自動クリーンアップ等）

知識共有: ミーティングからリポジトリへ

従来の知識共有

・週次のテックミーティングで共有
・Slack で質問 → 口頭で回答
・新メンバーに OJT で伝達
・「あの PR のレビューコメント見て」

Agent-First の知識共有

・設計判断は ADR (Architecture Decision Record) に記録
・規約は docs/conventions/ に明文化
・「なぜこうなっているか」はコード内のコメントに
・ミーティングの結論は design doc に反映

リポジトリを Single Source of Truth にする

## 知識共有のフロー

1. Slack で議論が発生する
2. 結論が出たら design doc にまとめる
3. PR で design doc を追加する
4. 実装が完了したら、設計の「なぜ」をコードコメントに
5. Slack には design doc へのリンクを貼る

→ 3 ヶ月後に同じ質問が出ても、design doc を参照すれば答えがある
→ エージェントも design doc を読んで正しい実装ができる

Show & Tell の進化

チーム内の知識共有セッション（Show & Tell）も変わる:

Before:

「この機能をこう実装しました」→ コードを画面共有

After:

「エージェントがこの環境で良い結果を出すために、
こういう仕組みを作りました」→ CLAUDE.md, テスト, linter を共有

共有すべきは「書いたコード」ではなく「エージェントが良いコードを書くために整備した環境」。

オンボーディング

Agent-First 時代のオンボーディング

新しいメンバーが最初に学ぶべきことが変わる。

従来のオンボーディング:
  Week 1: 開発環境セットアップ
  Week 2: コードベースの構造を学ぶ
  Week 3: 小さなバグ修正を担当
  Week 4: 新機能の実装に参加

Agent-First のオンボーディング:
  Day 1-2: 開発環境 + AI ツールのセットアップ
  Day 3-4: AGENTS.md → docs/ を読んでプロジェクトを理解
  Day 5: エージェントと一緒に小さなタスクを実行
  Week 2: エージェントに計画を渡して機能を実装
  Week 3: フィードバックループの改善に貢献
  Week 4: 新しい Golden Principles の提案

オンボーディングチェックリスト

## Agent-First オンボーディング

### Day 1-2: セットアップ
- [ ] リポジトリをクローン
- [ ] `make build` と `make test` が通ることを確認
- [ ] Claude Code をインストールし、CLAUDE.md を読む
- [ ] Cursor をインストールし、.cursorrules を確認

### Day 3-4: 理解
- [ ] AGENTS.md を読む
- [ ] docs/architecture/overview.md を読む
- [ ] docs/conventions/ を一通り読む
- [ ] 既存のコードパターンを 2-3 個確認する

### Day 5: 最初のタスク
- [ ] 小さなタスクを選ぶ（例: エラーメッセージの改善）
- [ ] docs/exec-plans/ に計画を書く
- [ ] Claude Code で実装する
- [ ] make check で品質を確認する
- [ ] PR を作成する

### Week 2: 本格的な実装
- [ ] 新機能のタスクを受ける
- [ ] 設計を design doc にまとめる
- [ ] エージェントに実装を依頼する
- [ ] レビューを受けてマージする

### Week 3: 環境改善
- [ ] テストやドキュメントの不足を特定する
- [ ] フィードバックループの改善を 1 つ提案する
- [ ] CLAUDE.md の改善 PR を出す

生産性の測定

測るべきでないもの

❌ Lines of Code (LoC)
  エージェントは大量のコードを生成する。LoC は品質を反映しない。

❌ コミット数
  小さな PR を高速で回す戦略では、コミット数は増えるが意味はない。

❌ PR 数
  同上。PR のサイズが小さくなれば数は増える。

測るべきもの

✅ Cycle Time (PR 作成からマージまでの時間)
  目標: 24 時間以内

✅ Deployment Frequency (デプロイ頻度)
  目標: 1 日 1 回以上

✅ Change Failure Rate (変更による障害率)
  目標: 5% 以下

✅ Time to Recovery (障害からの復旧時間)
  目標: 1 時間以内

これは DORA metrics として知られる指標であり、Agent-First Development においても有効。

チーム固有の指標

✅ フィードバックループの網羅率
  Golden Principles のうち機械的に検証されているものの割合

✅ ドキュメントの鮮度
  90 日以内に更新されたドキュメントの割合

✅ エージェント成功率
  エージェントに依頼したタスクのうち、大きな手直しなしで完了した割合

✅ 自動化されたレビュー指摘の割合
  レビューコメントのうち、本来 CI で検出できたものの割合
  （低いほど良い = CI が十分に機能している）

自律性と制御のバランス

Autonomy Spectrum

低い自律性                              高い自律性
|──────────────────────────────────────────|
  Copilot    Cursor Chat    Claude Code
  (補完)      (対話)        (自律実行)

制御: 高い                               制御: 低い
リスク: 低い                              リスク: 高い
速度: 遅い                               速度: 速い

タスクのリスクに応じた自律性の調整

高リスクタスク（患者データ、認証）:
  → 低い自律性: 人間が設計 → エージェントが実装 → 人間が詳細レビュー

中リスクタスク（新機能、API）:
  → 中程度の自律性: 人間が計画 → エージェントが実装 → CI + 軽いレビュー

低リスクタスク（リファクタリング、ドキュメント）:
  → 高い自律性: エージェントに任せる → CI で検証 → 自動マージ

自律性を高めるための投資

自律性を高めるには、「エージェントを信頼する」のではなく「エージェントが失敗しても安全な環境を作る」。

もっと自律的に動かしたい
  ↓
テストカバレッジを上げる
  ↓
linter ルールを追加する
  ↓
構造テストを充実させる
  ↓
CI パイプラインを強化する
  ↓
安全に自律性を高められる

定期的なチームプラクティス

Weekly: エージェント改善振り返り

## エージェント改善振り返り (15分)

1. 今週エージェントがうまくいったこと
   - どんなタスクで成功したか
   - 何が成功の要因だったか

2. 今週エージェントがうまくいかなかったこと
   - どんなタスクで失敗したか
   - 何が原因だったか
   - → 「何の能力が足りなかったか？」

3. 次週の改善アクション
   - ドキュメントの追加
   - テストの追加
   - linter ルールの追加
   - CLAUDE.md の更新

Monthly: Golden Principles レビュー

## Golden Principles レビュー (30分)

1. 既存の Principles は今も有効か？
2. 新しく追加すべき Principles はあるか？
3. すべての Principles が機械的に検証されているか？
4. エラーメッセージは十分に分かりやすいか？

Quarterly: Doc Gardening Day

## Doc Gardening Day (半日)

1. 全ドキュメントの鮮度チェック
2. 古いドキュメントの更新/アーカイブ
3. 不足しているドキュメントの特定と作成
4. AGENTS.md の全面レビュー
5. 新メンバー目線でのオンボーディング体験確認

Try This: チームワークフローの改善

Exercise 1: PR サイズの分析

過去 1 ヶ月の PR を分析する:

  1. 各 PR の変更行数とレビュー時間を記録する
  2. 大きな PR（200 行超）を特定する
  3. それぞれ「どう分割できたか」を検討する
  4. 次のスプリントから分割を実践する

Exercise 2: 知識の棚卸し

チームの暗黙知を特定する:

  1. 新メンバーが最初の 1 ヶ月で「人に聞かないと分からなかったこと」をリストアップする
  2. それぞれについて、リポジトリ内のドキュメントがあるか確認する
  3. ないものは docs/ に追加する

Exercise 3: 生産性指標の導入

DORA metrics の測定を開始する:

  1. Cycle Time を 1 週間計測する
  2. 現状のベースラインを記録する
  3. 改善目標を設定する
  4. 月次で推移を確認する

Exercise 4: 自律性マッピング

プロジェクトの各モジュールについて:

  1. リスクレベル（高/中/低）を判定する
  2. 現在の自律性レベルを確認する
  3. 自律性を高めるために必要な投資（テスト、linter 等）を特定する
  4. 優先度をつけて実行計画を立てる

まとめ

Agent-First チームワークフローの原則:

  1. 小さく速くマージする: Short-lived PR + follow-up で改善を継続
  2. リポジトリが Single Source of Truth: 知識はリポジトリに集約する
  3. オンボーディングは環境の理解から: コードの読み方ではなく、環境の使い方
  4. 正しい指標を測る: LoC ではなく DORA metrics
  5. 自律性は環境の整備で高める: 信頼ではなく安全な仕組みで
  6. 定期的な振り返り: エージェントの改善も継続的なプラクティス

学習パスの全体

このモジュールで Agent-First Development の学習パスは完了です。以下の順序で復習できます:

  1. パラダイムシフト - 役割の変化を理解する
  2. プロンプトエンジニアリング - エージェントに意図を伝える
  3. リポジトリ = 知識ベース - 知識を集約する
  4. フィードバックループ - 品質を機械的に保証する
  5. エージェントに優しいアーキテクチャ - 構造を設計する
  6. AI 開発ツール - ツールを使いこなす
  7. レビューと品質管理 - 品質を管理する
  8. チームワークフロー - チームで実践する（本モジュール）
←レビューと品質管理