PR数4倍でも破綻しない、Claude Codeをチーム運用する仕組み

Posted on 2/18/2026

はじめまして。Core PlatformでKARTEのJourney機能の開発に携わっている市川です。最近、GitHub元CEOのThomas Dohmke氏がXで次の投稿をして話題になりました。

“The concept of understanding and reviewing code is a dying paradigm.”

https://x.com/ashtom/status/2021255786966708280

この主張にはポジショントークの側面もあると思います。ただ、現場で「コード中心」から「意図・制約・成果中心」へ重心が移りつつあるのは確かです。弊社ではClaude Codeがデファクトになりつつあり、Codex（OpenAI Codex CLI）も一部利用しています。この記事では、チーム開発でClaude Codeを安定して回すために整備してきた設定と運用を共有します。

TL;DR

AGENTS.md / rules / docs で「何を知っているべきか」を設計する
Permission / Hooks で「やってはいけないこと」を機械的にブロックする
Skills / Subagents で「どうやるか」定型化、検証・レビューを隔離をする
設定はすべてリポジトリにcommitし、チーム全員が同じ環境で作業する

前提

モノレポで複数プロダクトを開発。Journeyは比較的新しい機能
言語はTypeScriptが多め。一部Go
複数リポジトリにまたがった開発が必要（インフラはTerraform/K8s manifest等で別リポジトリ）
1プロダクトを数名のエンジニアで担当し、要件定義〜運用まで持つ

現状の成果

Journey Teamはエンジニア約5名のチームで、2025年9月と比べて現時点でチームのPR数は約4倍（約150PR/月 → 約600PR/月）になりました。2/17時点で450PR以上Merge済みです。

また、担当者が変わっても「Issue整理 → Plan → 実装 → Verify → PR作成」の流れを再現しやすくなっています。新しく入ったメンバーや社内のメンバーからは、「Journeyでclaudeを起動すると賢い気がする」「どのように取り入れるべきか教えてほしい」という声も上がっています。

1. 課題と方針

AIエージェントを導入すると実装速度はまず上がります。ただ、チーム運用に乗せると別の問題が出てきます。

レビュー量の爆発 — PRの差分を全部人間が追う前提が重くなる
運用の属人化 — 「このプロンプトを知っている人」だけが早い
判断のブラックボックス化 — なぜその実装になったかが後から追えない

この課題に対して、「誰がコードを書くか」ではなく「意図・制約・成果をどう共有するか」を設計の軸にしました。

エージェントのスループットが人間の注意力・レビュー可能量を大きく上回る環境では、「修正のコストは比較的低く、待つことのコストが相対的に高い」という前提を考慮しなければいけません。つまり、手戻りを恐れて止め続けるよりも、一定の安全策を維持したうえで前に進み、問題は速いフィードバックループで回収するほうが、合理的になりやすいということです。

方針

上記の前提から、速いフィードバックループを回すことを目指しました。レビュープロセスは今まで通りやっていますが、「何をレビューすべきか」「何を省略できるか」「なにを最低限検証するべきか」も見えてこない。まず回して、そこから削る、重要なものは自動化する方向で進めています。

それ以外に設計として意識しているのは以下です

gitリポジトリ内の情報を正（System of Record）とする。NotionやSlackも使うが、正しい情報はあくまでgitに入れる。coding agentが触りやすい状態を作ります。
PRをできるだけ早くMerge/Closeする。人間のレビュー待ちをするよりも、早く動かして早く失敗を検知し、早く再発防止策を作ることにフォーカスしたほうが数年後のアウトプット量は増えると考えています。Journeyは比較的新しい機能だからできる部分も大いにあります。

作る順番

自分の普段の業務を棚卸しし「代替しやすく効果が高い」部分から作っていきました。

Codexと業務の棚卸しをしていたとき、「『自分が仕事した気分になる』業務から代替する方向で考えろ」とアドバイスされました。Codexのどストレートなところ大好きです。

「代替しやすく効果が高い」の基準

難易度が低い
時間がかかる

「代替をやめる」基準

判断理由を構造化して、チーム内で再現・共有できなくなったら、その作業の代替はやめる

この「再現可能性」を崩さないことが、個人活用とチーム運用の分岐点だと思っています。

2. 全体像

Claude Codeの設定と人間用ドキュメントを、アプリケーションコードと一緒にcommitしています。

project/
├── .claude/
│   ├── hooks/       # 自動実行フック
│   ├── plans/       # claudeのplanファイル（価値があるものだけcommit）
│   ├── rules/       # ファイル別ルール
│   ├── skills/      # スキル定義
│   ├── statusline.sh # statusline
│   └── settings.json # Project共有のPermissionやHooks、env設定
├── docs/            # 人間向け（ADR/オンボーディング/運用）
├── AGENTS.md        # プロジェクト説明（docs index含む）
└── apps/            # アプリケーションコード

これらの設定要素は、セッション中にそれぞれ異なるタイミングでContext Windowに読み込まれます。以下の図はその全体像です。

/context コマンドで実際のコンテキスト使用量を確認できます。セッション開始直後で約36k/200kトークン（18%）を使用しています。

2-1. Permission / Hooks — 「やってはいけないこと」を機械的にブロックする

AGENTS.mdやrulesにルールを書いても、Claudeが毎回従うとは限りません。機械的にチェックできるものはPermissionとHooks、Linterに落とし込んで、ルール違反を不可能にする方が確実です。

Permission

何か：settings.jsonで定義するツール実行制約
誰が起動するか：Claude Code — 常時適用
いつ使うか：すべてのツール実行時に適用される。
使用例：
- readコマンドはallow
- git push:* はask（毎回確認）
- rm -rf はdeny
- 段階的に追加する（まずはread系から）

Hooks

何か：ツール実行の前後に自動で走るスクリプト
誰が起動するか：Claude Code — ライフサイクルイベント（PreToolUse / PostToolUse / SessionStart等）
いつ使うか：「毎回確実に実行したいチェック」に使う。AGENTS.mdに書くと守られないルールも、Hooksなら確実
使用例：
- PostToolUse: Edit/Write後にPrettier/gofmtで自動format、typecheck
- PreToolUse: 保護ブランチへの直接commitをブロック、commit/push前にsecretlintで機密検知
- SessionStart: インストール済みのcli toolをClaudeにフィードバック

ポイントは、exitコードで「Claudeだけにフィードバック」か「Claudeとユーザー両方にフィードバック」かを制御できる点です。

Exit Code	stdout	stderr	用途
0	Claudeにフィードバック	ユーザーに警告表示	成功時の情報伝達
2	Claudeにフィードバック	両方にエラー表示	ツール実行をブロック
その他	Claudeにフィードバック	両方にエラー表示	hook自体の失敗

Claudeに早期にフィードバックすることで、想定外の動作がほぼなくなります。特にsecretlintがあると「とりあえずPR作成まで任せる」運用ができて安心感が高い。

2-2. AGENTS.md / rules / docs — 「何を知っているべきか」を設計する

基本的に「常時読ませたい」→ AGENTS.md、「編集対象限定の制約」→ rules、「人間が理解するための詳細」→ docs という使い分けをしています。

AGENTS.md

何か：Guidance — プロジェクト全体のコンテキスト
誰が起動するか：Claude Code — セッション開始時に自動読み込み
いつ使うか：プロジェクト全体に適用される規約・構成情報。「目次」として機能させ、詳細はdocs/に置く
使用例：
- プロジェクト構成（各ディレクトリの役割）
- docs index（圧縮インデックス形式）
- 開発ルール（TDD、Git運用、planファイル扱い）
- 利用可能MCPと推奨ツール
他ツール対応：Codex、Copilotも読める。CLAUDE.mdには @AGENTS.md のみ記載し、実態をAGENTS.mdに集約

記述量はBoris氏の5.3Kトークンを目安（https://x.com/bcherny/status/2015254548106170716）

どの階層にも置けます。Claudeがある子ディレクトリのファイルを読む前に、子ディレクトリのAGENTS.mdを自動で読み込みます。子ディレクトリのAGENTS.mdは構成を固定して、他の制約があればrulesに書いています。

rules

何か：Guidance — ファイルパターン別のコーディングルール
誰が起動するか：Claude Code — frontmatterのpath条件にマッチしたとき自動
いつ使うか：特定の言語やディレクトリに限定したルール。pathなしなら常時読み込み
使用例：
- **/*.ts → TypeScript規約（any禁止、interface優先、不変性）
- **/*.go → Go規約（context第一引数、datetimeパッケージ必須）
- apps/client/** → フロントエンド固有（テスト戦略、Storybook運用）
補足：subagentにも読ませたいものはAGENTS.md、そうでないものはpath条件なしrulesに書いています。

docs/

何か：Knowledge Base — 人間が読むドキュメント（Claudeもindex経由で参照可能）
誰が起動するか： Claude — AGENTS.mdの圧縮indexから必要な箇所を必要なときに参照
いつ使うか：設計背景、運用手順、ADRなど、AGENTS.mdに収まらない詳細情報
使用例：
- development/ — getting-started、開発手法
- architecture/ — システム構成、DB設計、コントラクト
- operations/ — DB操作、デプロイ、監視情報
- adr/ — 意思決定ログ（Architecture Decision Records）
運用ルール: コード変更と同時更新し、PR時に更新漏れを検知。

2-3. Skills / Subagents - 「どうやるか」定型化、検証・レビューを隔離をする

Skills

何か：Guidance, Instructions, Scripts — 定型ワークフローのパッケージ
誰が起動するか：人間が /skill-name で呼び出し。LLMがSkillのdescriptionから起動
いつ使うか：繰り返しの作業フローを再現可能にしたいとき。開発ワークフローの各フェーズに配置
使用例：
- /create-pr --wait — PR作成・CI監視・CI失敗時の自動修正・レビューコメント自動対応
- /verify — 変更種別に応じた動作確認。影響範囲の特定方法を固定
- /interviewing-issues — 4段階インタビューでIssue仕様を明確化
- /orchestrating-tdd — TDD自動実行（Red→Green→Refactor）
- /codex

基本的にはClaude Code公式やCodex公式のSkillを使い、ないものは /skill-creator で自作、/improving-skills で整えてから使用しています。

https://github.com/TomokiIchi/my-claude-skills/blob/main/skills/interviewing-issues/SKILL.md

Subagents

何か：隔離されたコンテキストで実行されるカスタムエージェント
誰が起動するか：Claudeが自動で起動（タスク内容に応じて判断）
いつ使うか：大量の中間出力が出る作業のとき。親コンテキストを汚したくないとき
使用例：
- db-reader — 全DB読み取りクエリを隔離。SubagentのHooksで読み取り専用に制限し、破壊的クエリのリスクなし
- code-simplifier — 実装完了後のコード簡素化

Subagentは「コンテキストの分離」と「Memory機能」が本質です。レビューや検証など大量の中間出力が出る作業を親セッションから分離できます。Boris氏もverify-appやcode-simplifierといったSubagentを活用しているとXで発言していました。

Boris Cherny on X

SkillsとSubagentの使い分け:

Skillsも context: fork でコンテキストを分離できます。実用上の違いは主に「誰が起動するか」と「memory機能の有無」です。

	Skills	Skills（context: fork）	Subagent
memory	なし	なし	あり（セッションをまたいで知識をprojectレベルに蓄積）
向いている用途	定型ワークフロー（PR作成, TDD等）	コンテキストを汚す作業（レビュー, 検証）	コンテキストを汚す作業（レビュー, 検証）
結果	セッションに直接反映	要約だけが親に返る	要約だけが親に返る

3. 外部連携ツール（MCP/cli）・実例

cliが存在するものはcliを、ない場合はMCPを導入しています。MCPのほうがコンテキスト消費が大きいため、cliで済むならcliを優先しています。

実際にSentryのエラートリアージ→修正の流れは以下のようになっています。

SentryのエラーはGitHub IssueにClaudeによってtriageされています。以下のフローをClaude Code上で完結できます:

（手動）/debug ${GitHub Issue URL}
ghコマンドでIssueをview、Sentry MCPでエラー詳細を取得
該当コードを特定し、原因を分析
cliやMCPでログやDB状態を確認
原因特定 → 修正実装 → /verify で検証
（手動） /create-pr --wait でPR作成・CI/レビューコメントの自動修正

以前は「Sentryを開く → コードを探す → ローカルで再現」とコンテキストスイッチが多かったのが、1つのセッションで完結するようになりました。

PRをopen時にGitHub Actions内でclaude-code-actionがレビュー用Skillを使用して自動レビュー。/create-pr --wait ではレビューコメントへの対応・非対応の判断と自動修正まで行います。

まだ課題として残っていること

コード品質の担保

PR数が増えた分、レビューの質を保つ仕組みが追いついていません。CIでの自動レビューは入れていますが、設計判断レベルのレビューは依然として人間に依存しています。

検証手段を与えることが最も重要だが、難しい

Boris氏は「Claudeに検証手段を与えれば品質が2-3倍になる」と述べています。単体テストの自動化は比較的簡単ですが、検証環境がローカルのポートや社内システムに依存している場合が問題です。現状は /verify で変更種別に応じたテスト実行を自動化しつつ、CI上では動かないものや並列で動かすと壊れるものがあり、妥協している部分があります。

https://x.com/bcherny/status/2007179861115511237

終わりに

「コードを理解しレビューする時代は終わる」——冒頭のこの言葉に今の自分なりの答えを出すなら、「コードの理解は終わらないが、その対象が変わる」だと思います。

読むべきは実装の詳細ではなく:

意図と制約がどう設計されているか（AGENTS.md / rules）
判断の境界がどこに引かれているか（Permission / Hooks）
プロセスが再現可能か（Skills / docs）

これは「コードを読まなくていい」という話ではなく、「何を読み、何を機械に任せるか」の設計が仕事になった、という話かなと理解しています。

今回すべては紹介しきれなかったので、また書きたいと思います。

付録

A. 導入しているMCP/cli一覧

ProjectレベルにはOAuth認証可能なMCPのみ設定を許可しています。一部ですがよく使うものたちはこれらです。

種類	ツール	用途	形式
仕様参照	Notion	仕様書の検索・参照	MCP (OAuth)
エラー調査	Sentry	エラー詳細・スタックトレース取得	MCP (OAuth)
監視	Datadog	ログ・メトリクス・モニター確認	MCP (OAuth)
データ分析	BigQuery	SQLクエリ実行	MCP + bq cli
ドキュメント	Context7	ライブラリ公式ドキュメント参照	MCP
デザイン	Figma	デザイン参照・コンポーネント確認	MCP (OAuth)
DB操作	gcloud spanner / wrench	Spannerクエリ・スキーマ管理	cli
GitHub	gh	PR・Issue・API操作	cli
Workflow	temporal	Workflow検索・履歴確認	cli

ルール:

最初は読み取り専用から
許可ツールを明示
書き込み系は段階導入
監査しやすい操作だけ許可

C. AGENTS.md紹介

実際のAGENTS.mdから一部抽出したものです。

# Journeyプロダクト

## 役割
あなたは Journey プロジェクトで作業する開発者です。

## プロジェクト構成
journey/
├── apps/
│   ├── client/         # フロントエンド（React + Zustand + tRPC）
│   ├── web/            # バックエンド API（Express + tRPC）
│   └── taskjob/        # TaskJob（Cloud Run jobs + Go）
├── packages/           # 共有パッケージ
├── docs/               # ドキュメント
└── schema/             # Spanner スキーマ

## ドキュメント
|development:{README.md,getting-started.md,temporal-workflow.md}
|architecture:{system-architecture.md,components/*/overview.md}
|operations:{kubernetes-environments.md,observability.md}

## 開発ルール
- pnpm --filter を使用（cd しない）
- TDD で実装

## 推奨ツール
- GitHub 操作: `gh` コマンドを使用（URL から情報取得する場合も `gh api` 等を使う）
- Issue 管理: Journey の Issue（Epic/Task）は必ず `/managing-github-project` スキルを使用する。`gh issue create` を直接使わない（Project 追加・Sub-issue 紐付け・フィールド設定が漏れるため）
- PR 作成: コミット・プッシュ・PR作成を一括実行する場合は `/create-pr` スキルを使用する
- DBクエリ: データベースへのクエリ実行時は必ず `db-reader` agent（`subagent_type=db-reader`）を使用する。Spanner / BigQuery / BigTable に対応。BigQuery MCP は破壊的クエリ（DELETE/UPDATE/DROP等）実行に注意。※本番環境はREAD権限のみ

D. 番外編: 実務で役立ったTips

コンテキスト確認： /context AGENTS.mdやrulesの認識状況を確認。statuslineにコンテキスト使用量を表示しておく
PRにIssueリンクをつける： AGENTS.mdに「planファイルにIssue URLを含める」ルールを書き、PRテンプレートにrefsとしていれるようにrulesに書いた。
Codex併用：ドキュメント構成やテスト戦略の壁打ちにはCodexが有効。実装はClaude Code、セカンドオピニオンはCodex
planファイル生成位置固定： plansDirectory を ./tmp/plans に固定。重要なものだけ /create-pr 時に .claude/plans/ にcommitさせる。
複数リポジトリ横断作業： additionalDirectories + CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1（addtionalDirectoryで作業する際にそこのAGENTS.mdを読む）+ CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1（cdしても起動ディレクトリに戻る）