パラダイムシフト: コードを書く人から設計する人へ
はじめに
ソフトウェアエンジニアの役割が根本的に変わりつつある。これまでの「自分でコードを書く」というモデルから、「エージェントが良いコードを書ける環境を設計する」というモデルへの移行が起きている。
この変化は単なるツールの進化ではない。仕事の本質が変わるパラダイムシフトだ。
"Humans steer. Agents execute."
OpenAI の Harness Engineering チームが掲げるこの原則は、新しい働き方の核心を突いている。
従来のモデル
エンジニア → コードを書く → テストする → レビューする → デプロイする
Agent-First モデル
エンジニア → 意図を設計する → エージェントが実行する → 結果を検証する → フィードバックを改善する
エンジニアの価値は「コードを書く速さ」から「エージェントが正しく動ける環境を整える能力」に移る。
日常業務の変化
1. コーディング → 要件定義と仕様記述
Before:
「この API エンドポイントを実装しよう」
→ エディタを開いてコードを書き始める
After:
「この API エンドポイントの仕様を明確にしよう」
→ 入力/出力の型、エラーケース、認証要件を docs/ に記述する
→ Claude Code に実装を依頼する
実際の作業例:
# docs/exec-plans/patient-search-api.md
## 目的
患者検索 API を実装する。部分一致検索をサポートし、
ページネーション付きで結果を返す。
## 制約
- レスポンスは 200ms 以内
- 検索結果は最大 50 件/ページ
- 患者の個人情報は認証済みユーザーのみアクセス可能
- 入力値は boundary で validation する
## 参照
- 既存の API パターン: src/api/handlers/medication.go
- 型定義: src/domain/patient/types.go
2. デバッグ → エラーメッセージの改善
Before:
バグ報告を受ける → ログを読む → 原因を特定する → 修正する
After:
バグ報告を受ける → エージェントがエラーメッセージから原因を特定できなかった理由を考える
→ エラーメッセージを改善する → エージェントに修正を依頼する
重要な洞察: 何かが失敗したとき、解決策は「もっと頑張る」ではなく「何の能力が足りないか？」を問うこと。
エラーメッセージの改善例:
// Before: エージェントには意味不明
return fmt.Errorf("invalid input")
// After: エージェントが原因を特定し修正できる
return fmt.Errorf(
"patient ID must be a valid UUID v4 format (e.g., '550e8400-e29b-41d4-a716-446655440000'), got: %q. "+
"Check that the client is sending the ID from the patient.id field, not patient.legacyId",
input,
)
3. コードレビュー → 自動品質ゲートの構築
Before:
PR を目視レビュー → スタイルの指摘 → ロジックの確認 → approve
After:
linter/型チェック/テストが自動で品質を保証する
→ 人間は「このアプローチは正しいか？」という判断に集中する
人間のレビューが最も価値を発揮する場面:
- アーキテクチャの方向性
- セキュリティ上の懸念
- ビジネスロジックの正しさ
- ユーザー体験への影響
環境設計という仕事
Agent-First Development において、エンジニアの主要な仕事は「環境設計」になる。
環境設計の 3 つの柱
1. Intent Specification（意図の明確化）
エージェントに「何をすべきか」を伝えるシステムを構築する。
- AGENTS.md / CLAUDE.md: リポジトリのテーブルオブコンテンツ
- Design docs: 設計判断の背景と理由
- Exec plans: 具体的な実装計画
- 型定義: コードレベルでの制約表現
2. Feedback Loops（フィードバックループ）
エージェントの出力が正しいかを機械的に検証する仕組みを構築する。
- 型チェック: コンパイル時にエラーを検出
- テスト: 振る舞いの正しさを検証
- Linter: スタイルとパターンの一貫性を保証
- CI/CD: 統合レベルでの品質ゲート
3. Knowledge Management（知識管理）
エージェントがリポジトリ内のすべての必要な情報にアクセスできるようにする。
- Progressive disclosure: AGENTS.md から詳細ドキュメントへの段階的な情報開示
- Doc gardening: ドキュメントの鮮度維持
- In-repo documentation: Slack や口頭伝達ではなく、リポジトリ内に知識を集約
具体的なスキルの変化
減っていくスキルの重要性
| スキル | 理由 |
|---|---|
| 構文の暗記 | エージェントが正確に生成する |
| ボイラープレートの手書き | テンプレートから自動生成 |
| 手動リファクタリング | エージェントが大規模変更を安全に実行 |
| コードスタイルの議論 | linter で機械的に強制 |
重要性が増すスキル
| スキル | 理由 |
|---|---|
| システム設計 | エージェントが動きやすい構造を作る |
| 要件定義 | 曖昧さを排除し、意図を正確に伝える |
| テスト設計 | エージェント出力の品質を検証する仕組み |
| ドキュメンテーション | エージェントの知識ベースを構築する |
| 問題分解 | 大きな問題をエージェントサイズに分割する |
| 判断力 | エージェントでは代替できない意思決定 |
医療 SaaS における特殊性
raica が扱う医療データには、Agent-First Development において特別な注意が必要な領域がある。
セキュリティとコンプライアンス
- 患者データの取り扱いルールをエージェントが理解できるよう、明示的に文書化する
- 認証・認可パターンをテンプレート化し、エージェントが一貫して適用できるようにする
- コンプライアンス要件を linter ルールとして機械的に強制する
ドメイン知識
- 医療ドメインの用語集をリポジトリ内に整備する
- ビジネスルール（保険制度、診療報酬など）をコードコメントと設計ドキュメントで明文化する
- エージェントが医療固有のバリデーションルールを理解できるようテストケースを充実させる
Try This: パラダイムシフトを体験する
Exercise 1: タスクの再定義
次に実装タスクに取りかかるとき、まず以下を書いてみよう:
docs/exec-plans/にタスクの実装計画を Markdown で書く- 入力/出力の型を明確に定義する
- エッジケースを列挙する
- 既存の類似実装へのパスを記載する
その後、Claude Code にその計画を渡して実装を依頼する。
Exercise 2: エラーメッセージの監査
自分が担当するモジュールのエラーメッセージを 10 個確認する:
- エージェントがそのメッセージだけで原因を特定できるか？
- 修正方法のヒントが含まれているか？
- 関連するファイルパスや設定値が記載されているか？
Exercise 3: レビュー観点の分類
直近 5 つの PR レビューコメントを振り返り、分類する:
- 自動化可能: linter やテストで検出できたはずのもの
- 人間の判断が必要: アーキテクチャ判断、ビジネスロジックの正しさ
自動化可能なものが多ければ、それはフィードバックループの改善余地を示している。
まとめ
Agent-First Development は、エンジニアの仕事をなくすものではない。仕事の種類を変えるものだ。
- コードを書く → コードが正しく書かれる環境を設計する
- バグを直す → バグが発生しにくい仕組みを作る
- レビューで指摘する → 指摘が不要な品質ゲートを構築する
この変化に適応するために必要なのは、新しいツールの使い方を覚えることではなく、「自分の役割は何か？」という問いに対する答えを更新することだ。
次のステップ
- プロンプトエンジニアリング実践 - エージェントに意図を正確に伝える方法
- リポジトリ = 知識ベース - エージェントのための知識管理