AI 活用でコード作成は加速、SDLC プロセスは遅延

コードがボトルネックではなくなった

組織は、1 年前には想像もできなかったスピードで AI を活用してコードを生成し始めています。しかし、コードを取り巻くプロセスは、その速度に追いついていません。

多くのエンジニアリングチームでは、承認ゲート、レビュー、引き継ぎ、ポリシーといった従来の仕組みがそのまま残っており、Claude Code のようなエージェント型コーディングソリューションによる生産性向上の足かせとなっています。

ソフトウェア開発ライフサイクル（SDLC）は、アイデアから本番環境へのリリースに至るまでのプロセスです。多くの組織で採用されているのは、計画、設計、構築、テスト、デプロイ、保守という 6 つの段階をカバーする標準的なバージョンです。従来、各段階は異なる役割が担当する独立したフェーズとして機能してきました。製品マネージャーが要件定義を行い、技術アーキテクトがそれを設計図に変換し、エンジニアがその設計を実装します。規制の厳しい企業では QA チームが検証を行い、リリースチームが本番環境へ展開し、運用チームが稼働状況を監視します。各フェーズ間の作業は、ドキュメント、チケット、承認といった形で引き継がれてきました。

従来のソフトウェア開発ライフサイクル（SDLC）は、各工程での責任とコントロールを確保するためにプロセスが重厚化しがちです。しかし、従来の SDLC は、最も時間とコストがかかる段階がコードの記述と実装である時代に合わせて設計されたものであり、現在はもはやその状況ではありません。

PRD（製品要件定義）や見積もり儀式、プロダクトセキュリティレビューなどは、開発に数週間から数ヶ月、あるいは四半期を要する期間において、関係者の合意形成を強制的に行うために存在していました。

従来の SDLC には、すべての工程が人間によって行われることを前提としたコントロールも含まれています。最も価値を生み出している組織は、エージェント型 AI が現在できることに焦点を当ててプロセスを再構築し、かつ人間の関与（ヒューマン・イン・ザ・ループ）を維持しています。

本ガイドでは、顧客との協業から得た知見に基づき、Applied AI チームが推奨するベストプラクティスを紹介します。Claude を SDLC の各段階に統合して開発を加速し、プロセスを高速化する方法について解説します。

コードがボトルネック不再是となり、ビルドフェーズが従来の SDLC が想定するよりも速く実行されるようになると、以下の 3 つの事実が浮かび上がります：

ボトルネックはビルドフェーズの前後、つまり計画・レビュー/テスト、そしてデプロイといった工程へと移っています。これらは依然として人間の速度でしか進められていません。

管理策が現実から乖離し、制御不能な状態に陥ります。人間が手作業で記述していた時代には、行単位でのレビューは理にかなっていましたが、差分の大部分をエージェントが生成するようになると、そのスピードについていけなくなります。

ガバナンスコストが増大します。例外処理が依然として週次や月次の会議・委員会を経由するためです。

ビルドがもはや制約要因ではありません。その周囲にある人間速度の工程こそがボトルネックです。人間速度の工程は依然として長い時間を要しますが、ビルド時間は数時間に短縮されています。

セキュリティ上のボトルネックを例に考えてみましょう。セキュリティチームは人間の生産性を基準に人員構成されているため、エージェントによってコード出力が増大すると、レビュー待ち行列が膨らむか、未審査のままコードがリリースされるかのどちらかになります。規制の厳しい組織ではどちらの結果も受け入れられないため、セキュリティチェックやポリシー検証はエージェントの速度に合わせて進める必要があります。

アジェンティック AI の生産性向上を最大限に実現し、かつ安全性を確保するためには、従来のソフトウェア開発ライフサイクル（SDLC）全体が、実装フェーズと同程度の抜本的な変革を遂げる必要があります。

AI ネイティブなSDLCとは何か

AI ネイティブなSDLCは、従来の制御目標と新しい強制力を組み合わせて再構築されたプロセスです。直線的なフローではなく、このプロセスはループ状となり、各段階にAIが埋め込まれます。これにより、従来のSDLCの各フェーズ間で行われる手動でぎこちない引き継ぎを解消し、次のアクションへの自動化された引き継ぎとトリガーを促進します。

変化の兆し

以下の表は、Claudeのサポートのもと、従来のSDLCとAI ネイティブなSDLCという両極端を比較したものです。多くの組織はこの2つの間にあるどこかに位置しています。

右側の列に流れる一貫したテーマは、コミットされた成果物です。各工程の終了時には、必ず 1 つの成果物をバージョン管理システムへ書き出します（intent.md、spec.md、plan.md、差分とそのテスト、レビュー結果を伴う PR、インシデント記録など）。そして次の工程では、その成果物を読み込んで開始されます。初期段階では、プロダクトオーナーとエージェントの両方が読み取り・実行できるため、.md ファイルが主要な成果物となります。ビルド以降は、コードとその記録が成果物の中心になります。コミットの連鎖自体が監査証跡となり、「誰が何を要求し」「エージェントは何を生成し」「誰が承認したか」が明確に追跡されます。

判断を要するすべての決定に対する責任は人間にあります。エージェント型 SDLC の世界では、レビュー対象となる成果物の変化に合わせて、人間の注力ポイントも移っていきます。

各工程でコミットされる成果物は、次の工程が読み取れる形で残されます。これら「意図」「仕様」「計画」「差分とレビュー結果」を合わせると、完全な監査証跡となります。

プレイ

プレイは本プレイブックの中核であり、非線形な 6 つのステージ（Plan, Design, Build, Test, Deploy, Maintain）に分類されています。これら全体でライフサイクルを網羅します。

各プレイでは以下の点を扱います：

• 変更される範囲；
• 着手方法；
• 具体的な実装ステップ；
• ガバナンス上の考慮点；
• 効果測定の方法。

これらのステップはモジュール化されており、組織は独自のニーズに基づいて、異なる時期に異なる工程の変革を優先順位付けして選択することができます。各プレイの「前提条件」には依存関係が明記されており、依存グラフによってさらに詳細に示されています。

ある工程は、次の工程を開始するコミットによってアーティファクトを確定させることで終了します。承認された intent.md が要件と設計の確認フェーズをトリガーし、承認された spec.md が計画モードを開始し、マージされた PR がパイプラインを実行し、本番環境で制御バンドが違反すると次の intent.md が生成され、ループは継続します。

最初は各ステップを手動でプロンプトして開始しますが、最終的には「承認されたアーティファクトが次のゲートを発火させる」というループ状態を目指します。人間の注力はゲートに集中し、エージェントが指摘した内容を確認するだけで済むため、毎回ゼロから工程を始める必要はありません。

*プレイは工程順にリストされていますが、矢印は導入すべき順序を示しています。これらは一致しません。いずれの「粘土（初期段階）」のプレイから始めても構いません。そこには入ってくる矢印がないため、先に必要なものはないからです。それ以外のプレイについては、そのプレイに向かっている矢印が、先に導入すべきプレイを指しています。

01

計画

アイデアは、誰かが書き起こすのを待たずに処理されます。意図（インテント）は、発案者自身の言葉で一度だけ記録され、次の工程がアクションを起こせるバージョン管理されたアーティファクトとして保存されます。

intent.md として捉える

ソフトウェア開発プロセスを起動する intent.md は、複数の経路から入力されます。個人がアイデアを持ち込む場合もあれば、チケットが作成されるケース、あるいはアラートを通じてインシデントが表面化するケースもあります（後述のステージ6：メンテナンス参照）。

個人がアイデアを持った際、Claude とブレインストーミングを行い、マークダウン形式のプロトタイプ仕様書を作成します。従来の SDLC では、その人物が製品チームのメンバーに説得し、自分自身または代わりにそのアイデアを文書化してもらう必要がありました。

Claude によって生成されたプロトタイプ仕様書は人間が読める形式であり、バージョン管理も可能で、次の工程ですぐに利用できます。この仕様書は intent.md として保存されます。

イベントトリガーから生成された意図であれ、エージェントからの提案であれ、コミット前にプロダクトオーナーがエージェント作成の intent.md をレビューし修正する手順は共通しています。

従来のアプローチでは、アイデアはバックログエントリ、ユーザーストーリー、ストーリーポイント、そして精査会議を経て初めて実行に移されます。各引き継ぎで所有権が移転するため、エンジニアリングチームに届く情報は、発案者が意図した内容から数段階も遠ざかったものになってしまいます。

AI ネイティブなアプローチでは、発案者は Claude とブレインストーミングを行い、その結果を自らの言葉で記述した intent.md（プロトタイプ仕様書）として残します。この成果物には「何を」「なぜ」「どのような制約下で」実現したいかが明確に含まれます。反復プロセスはスキルとしてエンコードされます。

始め方

前提条件

特になし。

インフラストラクチャ

エンジニアではない人でもClaudeにアクセスできます（claude.ai または Cowork）。合意された intent.md のテンプレートと、プロダクトオーナーが監視するバージョン管理された共通のホームが必要です。単一のプロダクトであれば、最もシンプルな方法はプロダクトリポジトリ内の intent/ フォルダを設けることです。この構成により、そこから派生したコードとアートの連鎖を隣接させて管理できます。意図（インテント）が多数のリポジトリにまたがる場合のみ、専用のリポジトリを設けることがオーバーヘッドに見合う価値があります。モノレポの場合はディレクトリとして扱います。Stage 3: Build のサイドバーでは、すでに記録を保持している Jira や要件管理ツールとの関係性について解説しています。

このセットアップは、プラットフォームチームまたはエンジニアリングチームが一度だけ行うタスクです。技術チームのメンバーが意図（インテント）のホームを立ち上げ、組織全体から多くの貢献者が参加するため、誰が書き込み権限を持つかを決定する必要があります。

リポジトリが存在すれば、Git の経験がない貢献者でも Git を直接使用する必要はありません。バージョン管理システム（例：GitHub）へのコネクタにより、Claude が claude.ai や Cowork から Markdown ファイルを代わりにコミットできるようになります。

実行方法

• 発案者は、自らの言葉で問題点を Claude に説明します。今日できないこと、アイデアの影響を受ける人々、より良い状態のイメージ、あるいは対象外となる範囲などを具体的に記述すれば十分です。形式的な言語は必要ありません。
• アイデアが具体化するまでブレインストーミングを行います。Claude は分析担当者が行うような質問を投げかけます。具体的には、スコープ、ユーザー、制約条件、そして成功の定義について尋ねます。
• Claude に、組織のテンプレートに従って intent.md を作成させるよう依頼します。このテンプレートは技術チームメンバーがスキルセットとして設定し、リーダーが承認したものを指します。これには問題点、提案される成果物、影響を受けるユーザーやシステム、制約条件、そして未解決の質問などが含まれます。
• 発案者は、Claude の誤解を修正します。

• intent.md を共有ホームにコミットします。著者とタイムスタンプが記録され、プロダクトオーナーがそこからアイデアを引き継ぎます。

# Intent: claims status self-service
Author: J. Ortiz (claims operations). Status: draft.

## Problem
Customers phone the contact center to ask where their claim is.
Handlers spend roughly a third of call time on status-only queries.

## Proposed outcome
Customers see claim status, next step and expected date in the portal.

## Affected users and systems
Claims handlers, portal team, claims-core API.

## Constraints
No new PII in the portal session. Existing authentication only.

## Open questions
Do third-party loss adjusters need access too?

ガバナンスの考慮事項

証拠となるのは、著者、タイムスタンプ、完全な改訂履歴を記載したコミットされた intent.md です。これは意図ホームの Git 履歴にログ記録されます。プロダクトオーナーが承認し、その意図をステージ 2（デザイン）へ進めるための「承認」または「却下」の決定は、マージまたはクローズレビューとして記録されます。\n

測定方法

先行指標

最初の会話から intent.md がコミットされるまでの時間。これは意図ホームの Git 履歴から読み取られ、著者とタイムスタンプが記録されています。期待値は、数週間にわたる聞き取りと洗練のプロセスから、数時間での完了へと短縮することです。

遅行指標

生存率、あるいはプロダクトオーナーが「Stage 2: Design」へ受け入れ、クローズしない intent.md ファイルの割合です。この「受け入れ」か「却下」かの判断は、アーティファクトのマージまたはレビューのクローズとして記録されます。また、同じ変更に対して最初の spec.md コミットが行われた後に intent.md へ加えられた変更数も指標となります。

02

デザイン

要件定義と設計は一つのセッションに統合されます。ポリシーは数週間後のレビューで発見されるのではなく、仕様書（spec）を作成する過程で即座に適用されます。

要件と設計

プロダクトオーナーの承認を得た後、Claude は受け入れられた intent.md を基に、要件および設計仕様の作成を行います。このプロセスは、ブランド、セキュリティ、コンプライアンス、UX に関する組織の スキル に基づいてガイドされます。

プロダクトオーナーはこの仕様書を確認しますが、作成自体は行いません。この工程の目的は、エンジニアリングチームが計画を立てられるよう、懸念事項を明確に示した仕様の策定です。

フロントエンド開発は最も明確な事例の一つです。intent.md が承認されると、プロダクトオーナーは Claude Design（ベータ版）でその内容に基づいてデザイン案を作成し、モックアップを反復して改善した上で、それを Claude Code にエクスポートして実装を行います。 （原文の技術表記: intent.md）

従来の開発プロセスでは、要件定義と設計は別々のチームが担当する独立したフェーズとして行われます。アナリストがアイデアを要件として形式化し、その後デザイナーがそれを設計へと変換します。この分離は責任の所在を明確にするために存在しますが、結果として処理が遅く、情報の損失も生じがちです。

AI ネイティブなアプローチでは、両方のフェーズが単一のプロンプトセッションで完結します。Claude が intent.md ファイルを読み込み、組織のスキルセットに制約されつつ要件と設計仕様を生成します。その際、懸念すべき領域は自動的にフラグとして示されます。

始め方

事前準備

ブランド、セキュリティ、コンプライアンス、UX ポリシーなどを「スキル」として記述した intent.md ファイルを作成してください。

インフラストラクチャ

Claude へのアクセス権限を持つプロダクトオーナーが必要です。エンジニアリングの専門知識は不要です。

実行方法

• プロダクトオーナーは、組織で利用可能なスキルを参照しながらセッションを開始し、intent.md ファイルを添付します。
• プロダクトオーナーのプロンプトでは intent.md を指し示し、制約事項を定義するとともに懸念点を明確に求めます。最初は手動で実行し、その後、組織レベルのスラッシュコマンドとして定式化してください。

そこから、意図のホームで intent.md の承認をトリガーとし、マージ時に非対話ジョブを実行して組織のスキルを読み込み、spec.md をプルリクエストとしてコミットします（CI/CD プレイの詳細はステージ 5：デプロイで解説しています）。この時点から、プロダクトオーナーの最初の関与はレビューとなります。

同じプロダクトオーナーが、アイデアに対して仕様書の内容を見直します。その仕様は提示された課題を解決しているか、intent.md から残されていた疑問点は回答済みか、あるいは次の工程へ引き継ぐべきかを判断します。

まず、フラグ付けされた懸念事項から順に処理を進めます。これらは分析担当者がエスカレーションしたポイントに相当するためです。プロダクトオーナーは、各懸念事項について関連するポリシーの責任者と協議して解決し、エンジニアが仕様書を確認する前にこれを完了させます。

spec.md を intent.md と一緒にコミットします。このファイルペアによって、「何を求められたか」と「何が決定されたか」が記録されます。

プロダクトオーナーは、組織が高リスクと分類する事項については技術リードに相談しつつ、仕様書と意図書の開発工程への移行を決定します。この判断は必ず人間が行い、仕様書を承認することが、ステージ 3：Build（構築）における「プランモード」プレイの開始を意味します。

何が見えるか（プロンプト）

Read the attached intent.md and produce a requirements and design spec for integrating it into our existing codebase. Apply the skills available to you so the plan conforms to our brand guidelines, security policies and UX standards. Document the spec fully as spec.md, ready to hand to the engineering team. Describe clearly any areas of concern, especially where you cannot satisfy contradicting policies.

ガバナンスの考慮事項

数週間後のレビューで発見されるのではなく、仕様が記述されている最中に生きたポリシーが読み込まれ、即座に適用されます。組織のスキルは、仕様に対する制約として機能します。仕様書、その作成に用いられたプロンプト、そして現在有効なスキルのバージョンはすべて、バージョン管理システムにログとして記録されます。プロダクトオーナーは仕様書を承認し、問題が指摘された場合は特定のポリシー担当者にエスカレーションします。

測定方法について

先行指標

同じ変更に対する intent.md のコミットと spec.md のコミットの間の経過時間（2 つの git タイムスタンプ）を、従来の要件定義から設計までのサイクルと比較して測定します。

後行指標

ビルド開始後に要件の再検討が必要になった場合、同じ変更に対する最初の plan.md コミットより後の spec.md のコミット数をカウントします。Git log を使用すればこれを直接確認できます。

03

ビルド

承認された計画がない限り、実装は行われません。組織のナレッジはエージェントが読み取るファイルとして管理され、ガードレールは習慣ではなくコードとして実行されます。

デフォルトの開始点として Claude Code のプランモードを使用

エンジニアは plan mode で Claude Code セッションを開始し、Stage 2: Design から承認された spec.md を Claude に渡します。その後、エンジニアが納得するまで計画についてインタビュー形式で対話し、計画を反復して洗練させていきます。

従来の開発プロセスでは、エンジニアが設計書を読み込んでコーディングを開始します。変更の具体的な方針や、どのファイルやテストに着手するかといった詳細は、エンジニアの頭の中か、せいぜいチケットのコメント欄に残るだけで、他者が確認できる状態にはなりません。レビュー担当者が目にするのは完成した差分のみであり、その段階では手戻りが生じると修正が困難になります。

AI ネイティブな開発プロセスは、Claude がプランモードで生成した文書化された計画から始まります。このモードでは、コードベースを読み取ることはできますが、変更を加えることはありません。エンジニアはコード記述前に計画を修正し、承認されたバージョンは後続の工程のために plan.md としてコミットされます。

チェック項目

始め方

前提条件

意図定義アーティファクト（intent.md または spec.md）があれば、また CLAUDE.md ファイルが用意されていれば役立ちます。

インフラストラクチャ

リポジトリへのアクセス権限を持つ Claude Code。

このツールは、開発プロセス全体を支援する AI ネイティブなソフトウェア開発ライフサイクル（SDLC）の指針として機能します。

実行方法

• エンジニアは、Claude と共に「計画モード」でセッションを開始します。
• intent.mdとspec.mdを Claude に渡し、変更対象のファイル名、作業順序、検証用のテストケースを含む実装プランの作成を依頼します。
• 「この変更がどこを壊す可能性があるか」「どの工程が最もリスクが高いか」「Claude が却下した他の選択肢は何か」といった質問を通じて、プランを検証・問い直します。
• 計画を読んだことのないエンジニアでも、それだけで実装できるレベルになるまで、何度も反復して洗練させます。
• 承認されたプランをplan.mdとしてコミットします。このプランは監査証跡の一部となり、PRレビュー（ステージ5：デプロイ）では、最終的な差分がプランと整合しているか確認されます。
• プランを受諾し、Claude に実装を任せます。堅牢なプランがあれば、実装は通常1回のパスで完了します。

実装が計画から逸脱した場合は、同じコミット内で plan.md を更新してください。両者の同期を強制するためにフックを使用することも検討してください。

実際の運用イメージ (plan.md)

# Plan: claims status self-service (from intent.md 2026-06-02)

## Files that change
portal/src/claims/StatusPanel.tsx (new), claims-api/routes/status.py,
claims-api/tests/test_status.py

## Order of work
1. Add the status endpoint behind existing auth.
2. Panel against the endpoint.
3. Wire into the portal nav.

## Risks
The claims-core API rate-limits at 50 rps; the panel must cache.

## Proof
test_status.py covers the four claim states; screenshot matches the
approved mock.

ガバナンス上の考慮事項

コード生成が行われる前、つまり方向転換がまだ文書の編集で済む段階で設計レビューを実施します。Plan モードはこのプロセスを自動的に強制します。Claude はエンジニアが計画を受諾するまでファイルの編集ができない仕組みになっているためです。計画とその改訂履歴は、誰が受諾したかという情報とともにログに記録されます。日常的な変更はエンジニアが承認しますが、組織が高リスクと分類する事項については、テックリードまたはアーキテクトへの承認フローを経る必要があります。

測定方法

先行指標

最初の開発フェーズでマージされた変更の割合、および PR メタデータに含まれる必要なデータと共に、計画承認からマージ済み PR までの所要時間。

遅行指標

PR メタデータに基づく変更ごとの再作業サイクル数、およびマージされた差分がコミットされた plan.md と依然として一致している頻度。

Claude Code の自動モード

Claude Code は、エンジニアが計画を承認し、満足して反復処理を行った後に、各編集ごとにプロンプトを出すことなく Claude が変更を適用する「自動モード」でも実行できます。後続のプレイでガードレール（調整済みの CLAUDE.md、ポリシーを記述したスキル、不安全なアクションをブロックするフック、Claude が実行可能なテストスイート）が成熟すれば、自動承認は日常的な作業のデフォルトとなります。具体的には、厳密な spec.md の作成、影響範囲（ブラスト・レイジ）の最小化、および既存のテストでカバーされているコードを対象とします。

このシフトは、エージェントによる編集をユーザーが監視しアクションを確認するスタイルから、より長い自律的なセッション後に成果物をレビューするスタイルへと移っています。自動承認モードは、ワークツリーを活用して個人間やチーム全体での並行処理をさらに可能にし、ステージ 6「メンテナンス」で説明されているように、SDLC を自律的に実行しループを完結させる上で不可欠な要素です。

サイドバー

レガシーシステムと真実の唯一の情報源

*プロセスが生成するすべての成果物に適用されます。*

既存の SDLC（ソフトウェア開発ライフサイクル）プロセスでは、すでにアーティファクトを追跡しているはずです。ただし、それは Markdown ファイルではなく、別のシステム上で行われているケースがほとんどです。作業項目は Jira に、要件定義は規制対応のトレーサビリティ機能が組み込まれたツールに、設計図は Figma に、変更承認は変更管理ボードで管理されているといった具合です。

これらの既存システムは、監査担当者や規制当局が既に採用しており、他のチームも依存しているため、容易には置き換えられません。そのため、AI ネイティブな SDLC は、既存の環境に適合する形で構築する必要があります。

AI ネイティブな SDLC へ移行する際、プロセスが生み出す各アーティファクトについて、「真実の唯一の情報源（ソース・オブ・トゥルース）」となるシステムを一つ指定し、他のシステムはそれのコピーまたはリンクを持つように設定します。以下の構成例では、アーティファクトの種類に応じて情報源の選択が異なります。

リポジトリを情報源とする構成

Markdown ファイルが権威ある記録となり、レガシーシステムはそのコミット内のファイルを参照します。これはエンジニア主導の組織にとって最もクリーンな構成の一つです。すべての記録が一つのツールに集約され、タイムスタンプの権限も一元化されるためです。

レガシーシステムを情報源とする構成

Jira、ServiceNow、または要件管理ツールが権威ある記録を持ち、Markdown ファイルは作業用コピーとして機能します。Claude はセッション開始時にその公式記録を読み込み、仕様書や計画を作成した同じセッション内で、MCP コネクタを介して結果を書き戻します。

リンクによる紐付けが最低限の要件です。 すべてのアーティファクトにはレコード ID を明記し、すべての従来型レコードには Markdown ファイルのコミット SHA を含めます。AI ネイティブな SDLC への移行においては、真実となるソースが二つ存在することを前提に、このリンクによる紐付けから始めるのが適切です。

従来のシステムと Markdown フォーカス型のシステムの両方が共存することは可能ですが、そのためには双方をリンクさせるか、どちらかを「唯一の真実源」として宣言しておく必要があります。

CLAUDE.md の活用

`CLAUDE.md` は、新入社員が必要とするコンテキストを提供するファイルです。チームが頻繁に犯すミスを避けるための規約、コマンド、アーキテクチャの指針などが網羅されています。これまで社員の頭の中や Wiki に存在していたナレッジを、エージェントがセッション開始時に読み込むファイルとして一元化し、チーム全体で維持・管理します。ミスが発生した際には随時更新される仕組みです。

始め方

事前準備

特にありません。

インフラ構成

リポジトリの用意、Claude Code のインストール、そしてコードベースに精通したエンジニアが一人いれば十分です。

実行方法

• リポジトリ内で /init を実行します。Claude が検出した情報をもとに、初期の CLAUDE.md ファイルを生成します。
• 生成されたファイルは、新規参画者が初日に必要とする内容に絞り込みます。ビルド・テスト・リンティングのコマンドや、重要な規約、そして Claude が繰り返し間違える箇所だけを維持してください。

リポジトリのルートに CLAUDE.md を git に追加し、チーム全員で単一のバージョンを共有して、変更内容をコードと同様にレビューできるようにしましょう。

ここで役立つ運用ルールがあります。Claude が同じミスを 2 回繰り返した場合、その修正内容を CLAULE.md に反映させるのです。

1 ページに収めるようにしてください。Claude はセッション開始時にこのファイル全体を読み込むため、古くなった情報が含まれていると、何の役にも立たないままコンテキストを圧迫してしまうからです。 （原文の技術表記: CLAUDE.md）

どのような形になるか（CLAUDE.md）

# Payments service

## Commands
- Build: make build
- Test: make test (unit), make itest (integration, needs docker)
- Lint: make lint (runs in CI; fix before pushing)

## Conventions
- Java 21, Spring Boot 3. No new Lombok.
- Money is always BigDecimal, never double.
- Every endpoint needs an integration test in src/itest.

## Architecture
- api/ holds REST controllers, core/ holds domain logic,
  adapters/ talks to external systems.
- Kafka events are defined in schemas/; never edit generated classes.

## Things Claude gets wrong
- Do not bump dependency versions; the platform team owns them.
- The legacy v1/ package is frozen; changes go in v2/.

ガバナンスの考慮事項

CLAUDE.md はバージョン管理されるため、エージェントが従う指示はレビュー可能で監査可能です。チームの規約はこのファイルを通じて適用され、その変更履歴は Git の履歴に記録されます。また、コード所有者が PR レビューにおいてこれらの変更を承認します。

測定方法

先行指標

CLAUDE.md で検出されるべきミスを Claude が繰り返す頻度です。修正内容や CLAUDE.md の変更点は、Git 履歴内で追跡する必要があります。

後行指標

チームに新メンバーが加わってから、最初の PR がマージされるまでの期間を PR 履歴から算出します。

スキルを組織の暗黙知として定着させる

スキルとは、組織が持つ暗黙知を実際の業務で活用するための手段です。指示は明確に記述され、バージョン管理が行われ、広く適用され、ポリシー変更時には中央集権的に更新されます。

基本原則：一貫して適用すべき組織の暗黙知については「スキル」として記述し、CLAUDE.md やプロンプトに含めるべきコンポーネントについては「スキル」にしないことです。

着手方法

前提条件

特に必要なし。CLAUDE.md を用意しておくとエージェントの作業知識をリポジトリ内に保持できるため便利ですが、スキルはそれなしでも作成可能です。

インフラストラクチャ

名付けられた責任者を持つポリシーと、信頼性の高い書面による真実源（ソース・オブ・トゥルース）が一つあれば十分です。

実行方法

• 今日、一貫して適用されていない知識の断片を一つ選びます。セキュリティ基準、API デザインの規約、ブランドルールなどが該当します。
• その知識を「スキル」として記述します。SKILL.md ファイルを含むフォルダを作成し、フロントマターでトリガー条件を、本文で具体的なアクションを定義します。エンジニアはポリシー所有者が管理する真実のソース（ソート・オブ・トゥルース）から書き起こし、Claude の支援を受けながら作成します。
• そのスキルをリポジトリ内の .claude/skills/ フォルダに配置してコードと一緒に配布するか、プラグイン を通じて組織全体で共有します。
• スキルが正しくトリガーされるかテストします。Claude に異なる方法で関連タスクを実行させ、毎回スキルが読み込まれることを確認してください。
• ポリシーに変更が生じた場合は、スキルも更新し、変更はポリシー所有者の承認を得てください。
• エンジニアは次のセッションで自動的に新しいバージョンを引き継ぎます。

実際の構成例 (.claude/skills/secure-api-review/SKILL.md)

---
name: secure-api-review
description: Apply the API security standard. Use whenever creating or
  modifying an external-facing endpoint, reviewing API code, or
  generating an OpenAPI spec.
---
# Secure API review

When you create or change an API endpoint:
1. Authentication: every endpoint requires the gateway JWT;
   no anonymous routes outside /health.
2. Input validation: validate request bodies against the OpenAPI
   schema and reject unknown fields.
3. Audit: every state-changing endpoint emits an audit event with
   actor, action, entity and timestamp.
4. Data classification: fields tagged pii in the schema must never
   appear in logs or error messages.

Run scripts/check-endpoints.sh and include its output in your summary.

ガバナンス上の考慮点

スキルは制御機能の一つですが、あくまで勧告的なものです。コード作成中に Claude がポリシーを適用する可能性を高めますが、セッションに対して強制力はありません。常に厳格に維持される必要があるポリシーには、スキルの背後に決定論的な仕組みが必要です。例えば、アクションをブロックするフックや、PR 段階でポリシーを再検証するレビューパスなどが該当します。スキルによって違反は稀になりますが、フックがあればほぼ不可能になります。スキルの呼び出しログはセッションのトレーシングに残され、ポリシー所有者はコードと同様にスキルの変更内容をレビューします。 （原文の技術表記: .claude/skills//）

測定方法

先行指標

ポリシー所有者が変更を承認してから、更新されたスキルがマージされるまでの所要時間。これはスキルのフォルダにあるプルリクエスト（PR）から取得します。

後行指標

ポリシーに言及した PR レビューでの指摘事項です。コード記述段階で既にそのポリシーが適用されている場合、これらの指摘はゼロに近づくはずです。もし指摘数が減少しない場合は、スキルがトリガーされていないか、あるいは適用されたテキストが公式のポリシーから逸脱している可能性があります。

ビルド時のガードレールとしてのフック

スキルは勧告的な制御機能ですが、フック はその背後にある決定論的なレイヤーです。Claude のアクションの多くは実装中のファイル編集やシェルコマンドであるため、フックが最も頻繁に発火するのはビルドフェーズとなります。

ビルドフェーズのフックには以下のような役割があります：

• 生成されたクラスや凍結されたパッケージなど、保護対象パスへの編集をブロックする；
• ファイル編集後にフォーマッターとリンターを実行し、コードの逸積を防ぐ；
• 機密情報を差分（diff）から排除する。

例外なくポリシーが維持される必要があるスキルの裏付けとしてフックを活用します。フックは一致するアクションごとに実行されるため、ビルドフェーズ用のフックは高速で、変更されたファイルに限定する必要があります。テストスイート全体を実行するなど、より重いチェックはコミット時や PR 段階で行うべきです。

人間の承認を求めるフックは、ステージ 5「デプロイ」のゲートに配置すべきです。ビルド中に承認を促すと、並列実行されているすべてのセッションにおいて人がクリティカルパス（最重要経路）に戻ることになり、ボトルネックとなるためです。

並列セッションとサブエージェント

エンジニアは一度に複数の作業ストリームを推進できます。

並列セッションとは、別のタスクを処理する独立した Claude Code インスタンスのことです。各セッションは独自の git worktree を持ちます。それぞれのセッションは他者のことを一切知らず、それらを統括しているエンジニアだけが共有する要素となります。

サブエージェント subagent は、単一のセッション内でスコープを限定されたヘルパーとして動作します。独自のコンテキストウィンドウとツール制限を持ち、アプリが期待通りに動作しているかを確認するなど、複数のタスクで繰り返される作業に適しています。

並列セッションによってエンジニアが同時に進行中のタスク数を増やすことができ、サブエージェントは各セッションを特定のタスクに集中させます。エンジニアの役割は、これらすべてを統括しレビューすることです。

従来のアプローチでは、エンジニアは一度に一つのタスクしか処理できず、一日や一週間の多くの時間をビルド、テスト、コードレビューに費やします。待機中に他のタスクへ切り替えることは可能ですが、コンテキストスイッチの負担が大きいことから、それを好んで行う人はほとんどいません。

AI ネイティブなアプローチでは、エンジニアは一度に複数の Claude セッションを起動し、それぞれを独立した worktree で異なるタスクに割り当てます。繰り返される作業は、独自のコンテキストとツール制限を持つサブエージェントとして処理されます。エンジニアの役割は、これらをオーケストレーションすることへとシフトし、最終的にはループの構築と監視へと至ります。

はじめに

前提条件

CLAUDE.md ファイルは、すべてのセッションがこれを参照します。フィードバックループ（ステージ 4：テスト）もここでの役割を果たします。セッションが自身の作業を検証できるため、エンジニアによる監視を最小限に抑えることが可能になるからです。

インフラストラクチャ

Git リポジトリが必要です。これは、ワークツリーと権限制御を適切に設定することで、組織が安全とみなすコマンドの実行に対して承認プロンプトを待たせることなく、セッションを隔離できるためです。

実行方法

• エンジニアは、プランモードプレイ（ステージ3：ビルド）の計画を参照して作業が独立している箇所を確認し、異なるファイルにまたがるタスクに分割します。同じファイルを共有するタスクは、1 つのセッション内で連続して実行されます。
• 並列化する各タスクには個別のワークツリーを用意します。例えば、一方のターミナルで claude --worktree feature-auth を、もう一方のターミナルで claude --worktree fix-rate-limit を実行するといった具合です。ワークツリーは独立したブランチ上の別チェックアウトであり、セッション間でのファイル競合を防ぎます。
• 並列セッション数は、2〜3 つから始めるのが適切です。実質的な上限は、1 人が適切にレビューできるストリームの数によって決まります。レビューが追いつく範囲でセッション数を増やしてください。
• 反復作業をサブエージェント化しましょう。.claude/agents/ ディレクトリ内の Markdown ファイルで定義されたサブエージェントには、名前、使用タイミングの説明、およびアクセス可能なツールの一覧を含めます。具体例としては、メインエージェントの処理後に不要な複雑さを除去するコード簡素化器、アプリを実行して動作を検証する検証用エージェント、コードベースを探索して報告するがメインコンテキストを溢れさせないリサーチャーなどが挙げられます。これらの定義は Git にコミットし、チーム全体で共有してください。

実際の構成例（.claude/agents/verifier.md）

---
name: verifier
description: Runs the app and checks the change works before the session
  reports done
tools: Bash, Read
---
Start the app with make run. Exercise the changed behavior and the two
nearest neighboring flows. Report what you ran, what you saw, and any
behavior that does not match plan.md. Do not fix anything; report only.

ガバナンス上の考慮点

セッション数が増えれば出力も増えるため、制御はリポジトリ内の設定ファイルから行う必要があります。ここで定義されたフックや権限設定は全セッションに適用され、各セッションの行動ログには実行したエンジニアの名前が紐付けられます。

評価方法

先行指標

レビュー品質を維持したままのエンジニアあたりの同時セッション数（OpenTelemetry エクスポートから算出）と、待機ではなく制御に費やす時間の割合。

後行指標

エンジニアあたりの週次マージ変更数と、PR 履歴に基づいて算出されるやり直し率を併せて確認する。

04

テスト

すべてのセッションは人間が確認する前に必ず自己検証を行い、エージェントを制御する設定も、生成されたコードと同様に回帰テストの対象とする。

Claude にフィードバックループを与える

Claude には、常に自身で作業を検証できる手段（テスト、ビルド、スクリーンショット差分など）を用意してください。セッションはエンジニアが確認する前に、自身のミスを発見して修正します。

このフィードバックループと、検証用サブエージェント（ステージ 3: ビルド）を混同しないでください。フィードバックループは作業量に応じて何度もタスク全体を実行しますが、検証用サブエージェントはセッション側で作業完了と判断された時点で、新しいコンテキストウィンドウを起動して最終チェックを行うパッケージ化手法の一つです。これにより、コード生成の前提条件にバイアスされない客観的な判定が可能になります。

従来の開発では、コードが動作しているという信号が届くのは遅れます。CI では数分後、テスターによる検証は数日後、本番環境への展開に至っては数週間後です。エージェントがコードを生成する状況でこの遅延が生じると、人間がすべての出力をチェックする必要が生じ、その人がボトルネックとなります。

AI ネイティブなソフトウェア開発ライフサイクル（SDLC）では、人間が確認する前にシステム自身が作業を検証できる仕組みを備えることが重要です。テストを実行し、ビルドを行い、スクリーンショットを取得します。Claude はチェックが通過するまで反復処理を続け、エンジニアに届く成果物はすでに検証済みとなります。

このループの構築は実行するエンジニアの役割であり、以下の手順も彼ら向けに記述されています。

はじめに

前提条件

特になし。

インフラストラクチャ

ローカル環境でそれぞれ 1 コマンドで動作するテストスイートとビルドが必要です。UI 関連の作業では、Claude が結果を確認できる手段が不可欠です。ブラウザツールか、MCP を経由して接続されたスクリーンショット取得ユーティリティのいずれかが必要となります。

実行方法

• 今日の実行確認に複数のコマンドや環境知識が必要になる場合は、失敗時に非ゼロの終了コードを返す「make test」や「npm test」のような単一のターゲットにまとめましょう。
• CLAUDE.md の Commands セクションには、各コマンドについて健全な出力の例も併記してください。
• クロードが質問なしで作業を検証できるように、定量化可能な目標を明確に設定します。例えば、「test_status.py の全テストがパスする」「スクリーンショットが添付されたモックと一致している」「新フィールドを含むエンドポイントが 200 を返す」などが具体例です。
• バグ修正の場合は、まず失敗するテストを書きます。そして、そのバグを再現するテストとして Claude に実行させ、期待通りの理由で失敗することを確認します。そのテストをコミットした上で、テストファイルフック（最終ステップのもの）による制限を適用しつつ、テスト自体は編集せずにパスさせるよう Claude に指示してください。修正前に存在し、エージェントが書き換えられなかったテストが通ることで、バグが解消された証拠となります。
• UI 関連の作業では、視覚的な確認でループを完結させます。Claude にブラウザまたはスクリーンショットツールとモック画像を与え、反復処理を行わせます。「実装→スクリーンショット取得→比較→調整」のプロセスを数回繰り返すのが一般的で、その都度結果は改善されていきます。
• 検証プロセスを「完了」の定義に組み込みましょう。指示は CLAUDE.md に記載します。タスク完了と報告する前に必ずテストを実行し、その出力も提示してください。

最後に、ループ自体の保護も必要です。コードを修正するエージェントが、そのコードに対するチェック機能を弱めてはならないからです。修正タスク中にテストファイルへの編集をブロックするフックを実装することでこれを達成できます。あるいは、レビュー時に差分を確認し、テスト関連の変更を含むものはすべて拒否するという方法もあります。

具体的な仕組み（CLAUDE.md 検証ブロック）

## Verifying your work

- Build: make build (must finish with "Build succeeded")
- Test: make test (all green; never skip or delete a failing test)
- Lint: make lint (zero warnings)

Run all three before reporting any task complete, and paste the output.
If a test fails, fix the code, not the test.

ガバナンスの考慮事項

何が強制されるか

タスク完了前の検証と、修正中にエージェントがテストファイルを編集することを防ぐ措置。これらは組織が必要とする箇所で確実に機能するよう、フックとして実装されます。

証拠とは何か

「make test」の実行結果、ビルドログ、あるいは Claude が実行して貼り付けたスクリーンショットの差分などです。証拠はツールチェーンから直接得られます。

どこに記録されるか

セッショントランスクリプト（OpenTelemetry エクスポートを通じて組織の観測スタックへ転送）と、PR のチェックランです。レビュアーや後の監査者はどちらもここで確認できます。

誰が承認するか

コードオーナーである PR レビュアーです。機械的な証拠は既に添付されているため、彼らは意図とリスクに集中して判断できます。

測定方法

先行指標

エージェントが作成した変更に対する CI の初回パス成功率（CI システムで既にサポート済み）。

後行指標

PR あたりのレビュー時間（PR メタデータから取得）。テストが従来のレビュアーが行っていた検出を担うようになれば、この時間は短縮されるはずです。また、インシデントトラッカーからの変更失敗率も重要な指標となります。

CI における継続的評価

評価（evals）は、AI ネイティブな開発ライフサイクルにおけるステージゲート QA の equivalents です。具体的には、エージェントの設定が変更されるたびに実行される一連のテストスイートを指します。新しいモデルに切り替えたり、プロンプトを再設計したりした際にも、その評価スイートによって「以前と同じ基準で作業ができているか」を検証できます。

この評価は生きた（ライブ）スイートとして捉える必要があります。モデルが改善されるにつれて、かつては明確な差をつけていたケースも区別できなくなるため、継続的なモニタリングから新たなケースを随時追加していくことが不可欠です。

ユースケースによっては、すべての変更ごとに実行するのではなく、一定のサイクルでオフライン環境で評価を実行することを好むチームもあるでしょう。以下に示す手順は、継続的評価（continuous evaluations）を対象としたものです。

着手にあたって

前提条件

• CLAUDE.md の整備
• フィードバックループ（ステージ 4: テスト）の確立

インフラストラクチャ

• クラウドコードを非対話モードで実行可能な CI 環境
• 評価実行用の予算が確保された API キー

実行方法

• プラットフォームエンジニアは、直近の業務から期待される結果や承認された成果を含む 20〜50 の実務タスクを収集します。
• これらのタスクそれぞれを評価用テスト（eval）として記述します。具体的には、プロンプトと、合格基準（テストパス、リンティングエラーなし、動作不変、ポリシー準拠など）を定義するチェックを組み合わせた形式です。
• このテストスイートは、CI 環境で非対話的にスケジュール実行されます。また、CLAUDE.md やスキル、フックに変更があった際にも即座に実行されます。これらはエージェントの動作を制御する設定であり、コードと同様に回帰テストの対象となるべきだからです。
• 設定変更はテスト結果によってゲート管理します。パス率が低下するようなスキルの変更は、マージ前にレビューを受ける必要があります。
• 本番環境でのインシデントが発生した際は、その担当チームが評価用テストを作成し、回帰テストとしてスイートに恒久的に登録します。

実際の構成例（.github/workflows/agent-evals.yml）

name: Agent evals
on:
  pull_request:
    paths: ['CLAUDE.md', '.claude/**']
  schedule:
    - cron: '0 2 * * *'
jobs:
  evals:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @anthropic-ai/claude-code
      - name: Run eval suite
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          for eval in evals/*.json; do
            claude -p "$(jq -r '.prompt' $eval)" \
              --allowedTools "Read,Edit,Bash(make test)" \
              --output-format json > result.json
            ./evals/check.sh "$eval" result.json
          done

ガバナンス上の考慮点

評価用テストは QA の役割を果たし、エージェントの出力に対するゲートを維持します。パス率の閾値はマージチェックとして強制され、実行ログは時系列で結果を比較可能に記録されます。また、設定変更の承認権限は、その変更を担当するチームが持ちます。

測定方法

先行指標

評価用テストのパス率は t