中間管理職がClaude Codeと仲良くなるまでの5週間
タグ: Claude ClaudeCode AI 開発プロセス ポエム
この記事は3部構成です。
- 失敗談：35件のIssueを一括処理させてコードが全崩壊した話
- 構成解説：Claudeを「組織」として動かすための設計思想
- 具体例公開：agentの定義・hooksの実装・フォルダ構成をそのまま公開
自己紹介
40代。エンジニアではない。コードはしばらく書いていない。
そんな中間管理職が、Claude Codeを使って80要件ある案件管理ダッシュボードを作ろうとした。
ただし「作った」ではなく、毎回スクラッチから同じ80要件を渡して、最もよく動くClaudeの構成を検証し続けている、という記録。
そもそもの動機
きっかけは実案件だった。
Claude CodeによるIssue駆動開発を実案件で見て、「これはすごい」と思った。自分でもやってみたくなった。
だから最初のスタートは業務で通用するスキル構成を意識していた。
1週目：「ちゃんとやった」のに壊れた
最初から雑にやっていたわけではない。
IssueもClaudeに書かせて、完了条件も入れて、Issue駆動開発のあるべき論を一通り取り込んだ状態でスタートした。
結果は、バグは出るけど使えるものができた。
起動しない。エラーをClaudeに貼る。直る。また起動しない。また貼る。直る。これを何度か繰り返すと、使えるレベルのものが出来上がった。
これはすごいと思った。これでも開発案件は回ると思う。
ただ、自分は最初から品質が良いものを作れるようにしたかった。
「バグを直し続けるんじゃなくて、最初からちゃんと動くものを作りたい。」
そのモチベーションで、毎週スクラッチから同じINPUTで構成を変えて試し直している。1週やって壊れる。原因を考えて構成を変える。また試す。それを5週繰り返している。
第1部：とにかく壊れた
最初の1週間：「これはすごい」
Claude Codeを使い始めた最初の感想は、正直、感動だった。
「ダッシュボードのログイン画面作って」と言えば作る。
「このボタンを左に動かして」と言えば動かす。
エンジニアじゃなくても、動くものが作れる。
2〜3週間目：「あれ、なんかおかしい」
機能が増えるにつれて、こういうことが起き始めた。
- さっきまで動いてたところが動かなくなる
- 「修正しました」と言われるが、別のところが壊れる
- 気づいたら「なんとなく動いてる、でも信用できない」状態
最初は自分の指示が悪いのかと思った。何度やっても同じことが起きた。
壊れた話①：「できました」が信用できない
Claudeが「完了しました」と返してくる。でも実際に画面を開くと動かない。
Claudeは「テストが通った＝完了」と判断していた。 でもテストが通っていても、ブラウザで実際に触ると全く動かないことが何度もあった。
あるリリースでは、出してから4回連続でやり直しになった。
CLI修正 → エラーハンドリング修正 → UTF-8修正 → UI修正
1つ直したら別が壊れる。これが延々と続いた。
最大の失敗：2026年3月28〜29日
ここが一番きつかった。開発ログにしっかり残っている。
3月28日：35件のIssueを「全部つくって」と渡した
「全部つくって」というひと言を受けて、Claudeが35件のIssueを一括処理し始めた。
何が起きたか：
| 何をしたか | 結果 |
|---|---|
| 複数Issueを並行処理（3〜6エージェント同時） | 同じファイルに並行書き込み → コード整合性崩壊 |
| 詳細設計書を一度も読まずに実装 | ボタンなし・リンクなし → UX破綻 |
| レビュー・テスト・受け入れ確認を全省略 | 見た目だけのハリボテが完成 |
| テストPASS＝完了と誤認 | ブラウザで操作するとNOT FOUND大量発生 |
| 「全部やって」＝「ルール無視OK」と解釈 | 1Issue単位の委譲ルールを完全無視 |
全コード破棄＆やり直しの寸前まで行った。
3月29日：対策したのに同じことが起きた
前日の失敗を受けて対策を打った。のに、翌日また同じ事故が起きた。
- 52Issueのうち49Issueで要件確認を省略
- 「テストが通った＝完了」という誤認が続く
- Issue-01は丁寧にやっていたのに、Issue-30以降は省略だらけに劣化
ここで気づいた。
これは指示の問題じゃない。構造の問題だ。
なぜ壊れるのか、ようやく分かってきた
5週間付き合って、核心に気づいた。
あるとき、Claudeがこういうニュアンスのことを言っていた。
「トークンを節約して、早く結果を出すことが、最も良い結果だと思っています」
QCDで整理するとこうなる：
| Claudeの傾向 | |
|---|---|
| Q（品質） | 自分では担保しきれない |
| C（コスト：トークン） | 最小化しようとする |
| D（納期：速さ） | 最速にしようとする |
Claudeは「早く・安く」を最大化しようとする傾向がある。品質（Q）は外から構造で与えないと守られない。
悪意は全くない。むしろ「頑張った結果」がそうなる。だから制御しないと、必ずショートカットする。
第2部：だからこの設計にした
基本思想：Claudeを「組織」として動かす
Claudeを1人のAIとして使うのをやめて、役割を持ったチームとして動かす。
人間の開発組織と同じ構造にする。そしてそれぞれが自分の役割以外のことを構造的にできないようにする。
自分（ユーザー）
↓
PM（唯一の窓口）
↓
設計担当 開発担当 テスト担当 リリース担当
自分が話すのはPMだけ。他はPM経由。
各担当の役割と「できないこと」
| 役割 | やること | 構造的にできないこと |
|---|---|---|
| PM（agent-pm） | 自分との窓口・全体調整・Phase管理 | コードを書く・直接修正（1行でも） |
| 設計担当（agent-doc） | 要件定義・設計書（HTML形式） | 実装する |
| リードEng（agent-lead） | TDD・テスト先行作成・レビュー | src/に書き込む |
| 開発担当（agent-dev） | 実装だけ | tests/に書き込む |
| テスト担当（agent-test） | ユーザー視点のUAT作成 | src/とtests/に書き込む |
| リリース担当（agent-deploy） | 確認済みのものだけリリース | src/に書き込む・前工程未完了のリリース |
「できないこと」を構造的に作るのがポイント。
PMが「1行くらいなら」と直接修正しようとしても、ルール上できない。これが3月28日の事故の再発を防ぐ。
意図的な対立
各担当に異なる価値観を持たせる。対立が品質を守る。
| 担当 | 優先すること | 抑制する相手 |
|---|---|---|
| PM | UX・シンプルさ・費用対効果 | リードの過剰品質追求 |
| リードEng | 品質・設計の正しさ | PMのシンプルさ優先 |
| 開発担当 | 設計通りの実装 | 設計担当の過剰仕様 |
| テスト担当 | ユーザー視点 | 全員（ユーザーが困る場面を発見する） |
| リリース担当 | 安全なリリース | 未完了リリース要求を拒否 |
対立が発生したときはGitHub Issueのコメントで主張を記録し、PMが裁定する。
「急いでいるから」「些細な修正だから」はルール違反の理由にならない。
核心①：command / skill / agent の違いと使い分け
ここが設計で一番重要だと気づいた部分。
Claude Codeには3つの「動かし方」がある。
command と skill：「会話の延長」として動く
同一セッションで動く
└ 会話履歴をずっと引き継ぐ
└ 前の文脈・前の判断・前の間違いも全部引き継ぐ
└ 状態がどんどん蓄積される → コンテキスト汚染
Issue-01で丁寧にやっていたのに、Issue-30以降は省略だらけになった（3月29日の事故）のも、これが原因のひとつだった。会話が積み重なるほど、初期の「ちゃんとやる」姿勢が薄れていく。
agent：「役割付きの独立実行」として動く
サブセッションとして動く
└ 指示ベースで起動される
└ コンテキストが限定される
└ 状態が圧縮される → 役割に集中できる
agentは「完全に無記憶」ではない。でもコンテキストを強制的に限定することで、前の会話の汚染が入りにくくなる。
agentの定義ファイル（実際の形式）
各agentは .claude/agents/ に以下の形式で置く：
---
name: agent-dev
description: 開発エンジニア。テストをパスさせる実装を行う
tools: Read, Write, Edit, Glob, Grep, Bash
memory: project
---
（ここにシステムプロンプトをMarkdownで書く）
tools で使えるツールを制限できる。これが「構造的にできないこと」の実装方法。
たとえば agent-dev は tests/ への書き込みを禁止するため、プロンプトに明示する：
「tests/ への書き込みは禁止です。テストはリードエンジニアが書きます。」
核心②：hooksで「止める」
ここが一番重要。Claudeは止めないと進み続ける。
Claude Codeには「hooks」という仕組みがある。特定のタイミングで処理を差し込んで、強制的に止めたり、条件チェックしたりできる。
PreToolUse hook → ツールを使う前にチェック（exit 2でブロック）
PostToolUse hook → ツールを使った後にチェック
Stop hook → Claudeが止まろうとしたときに介入
hooksでやっていること①：Release Gate
release/ フォルダへの書き込みを検出すると、PostToolUse hookが自動的にチェックリストを出力する。
agent-deploy が release/ に書き込む
↓
PostToolUse hook (release_gate_check.sh) が検出
↓
Phase 8〜14 の完了条件チェックリストを強制出力
↓
PM がチェックリストを確認
↓
未達項目あり → 該当Phaseに差し戻し
全項目PASS → リリース続行
チェックリストの中身（抜粋）：
- 対象Issueは1件のみか（複数Issue一括リリース禁止）
- Phase 8（TDD）: テスト存在 + 要件カバレッジレビュー完了
- Phase 9（実装）: 全テストPASS
- Phase 10:
/simplify実行済み - Phase 11: レビュー + Playwrightスクリーンショット + デザインレビュー
- Phase 13: UAT仕様書 + 受け入れテスト全PASS
- Phase 14: run.bat動作確認 + SHA256ハッシュ記載
チェックリストをパスしないと物理的にリリースできない。
hooksでやっていること②：Issue完了ブロック（1 Issue = 1 会話の強制）
これが一番強い制御。
1つのIssueが完了（gh issue close 実行）すると、同一会話内での全操作をブロックする。
agent-deploy が gh issue close を実行
↓
PostToolUse hook (mark_issue_completed.sh) がフラグファイルを作成
.claude/stop_after_issue
↓
以降の全ツール呼び出し時に PreToolUse hook が発火
↓
フラグが存在する → exit 2（ブロック）
↓
Read以外の全操作が不可能になる
↓
新しい会話を claude.bat で起動 → フラグ自動削除 → 復帰
ブロック対象：
| ツール | フラグあり | フラグなし |
|---|---|---|
| Bash | ブロック（gh issue list のみ例外） | 通過 |
| Edit / Write | ブロック | 通過 |
| Agent | ブロック | 通過 |
| Read | 通過 | 通過 |
claude.bat をダブルクリックするだけで起動でき、フラグも自動削除される。このバッチファイルもClaudeに書かせた。
これで「1 Issue = 1 会話」が技術的に保証される。
hooksで詰まったこと（実体験）
hooksは強力だけど、最初は全部壊れていた。
- PATHが解決できない
- エンコーディングがおかしい
- stdin JSONの解析が不正
- exit codeの使い方が間違っていた
これも全部「なぜ動かないのか」をClaudeに聞きながら解決した。自分で調べたわけではない。
特にexit codeは「ブロックするには exit 2 が正しい。exit 1 では止まらない」という仕様で、Claudeに聞いて初めて分かった。
エンジニアじゃなくても、Claudeに聞きながら仕組みを作れる。それ自体がこの検証のポイントでもある。
実際のブロック用スクリプト（block_after_issue_complete.sh）はこういう構造：
#!/bin/bash
# フラグファイルが存在したら exit 2 でブロック
if [ -f ".claude/stop_after_issue" ]; then
echo "Issue completed. Start a new conversation."
exit 2
fi
exit 0
exit 2 を返すとClaudeがツール実行をブロックする。exit 1 では止まらない。これもClaudeに書かせて、動かなくて、Claudeに聞いて、exit 2だと分かった。
設計を先に固める
Issueの前に設計を固定する。
詳細設計書を渡し忘れて実装させたら、ボタンもリンクもないUIが完成した（3月28日の事故）。
今の順番：
1. Issueを全部洗い出す（全体を先に整理）
2. 要件定義書（010）を作る
3. 基本設計書（020）を作る
4. 詳細設計書（030）を作る
↓
5. Issueごとに実装（設計書通りに・1つずつ）
6. 自分で確認（UAT）
7. 次のIssueへ
Claudeへの指示も変わった：
「設計書の通りに作って。それ以上のことはしなくていい。」
「創造させる」のではなく「設計に従って実装する機械として動かす」イメージ。
設計書をHTMLで作る理由
設計書は全部HTML形式で管理している。Markdownではなく。
理由はシンプルで、ブラウザで開けば非エンジニアでも読めるから。
サイドバー付き目次、検索バー、FR-IDカード（要件ごとのカード）、トレーサビリティマトリクス（要件→設計→Issueの対応表）がHTMLなら実装できる。
「触れる状態」を完了条件にする
「テストが通った＝完了」を禁止した。
今の完了条件：
自分（非エンジニア）が実際に触って確認できる状態。
| NG（未完了扱い） | OK（完了） |
|---|---|
| テストが通っている | 画面がある |
| 内部的には動いている | ボタンが押せる |
| APIだけ完成 | 結果が確認できる |
| 単体では動く | 一連の流れが試せる |
UAT仕様書もHTML形式で作っている。ブラウザで開いて、PASS/FAIL/N/Aをクリックでトグルできる。結果はlocalStorageに自動保存される。
「ユーザーが触れないものは完了ではない」をルールにした。
全体の構成（公開）
.claude/
├── commands/
│ └── agent-pm.md # PMの起動コマンド（ユーザーが呼び出す）
│
├── agents/ # 各エージェントの定義
│ ├── agent-pm.md # PM：唯一の窓口（opusモデル）
│ ├── agent-pm-ideation.md # PM壁打ち：漠然とした相談をIssueに整理
│ ├── agent-lead.md # リードEng：TDD・レビュー・環境構築
│ ├── agent-lead-ideation.md # リードEng壁打ち：技術評価・影響分析
│ ├── agent-doc.md # 設計担当：要件定義・設計書（HTML）
│ ├── agent-doc-ideation.md # 設計担当壁打ち：設計書への影響分析
│ ├── agent-dev.md # 開発担当：実装専任
│ ├── agent-test.md # テスト担当：UAT作成・ユーザー視点
│ ├── agent-design.md # デザイン担当：UX・画像生成プロンプト
│ ├── agent-deploy.md # リリース担当：リリース資材・バージョン管理
│ └── agent-git.md # Git運用ルール（全エージェント共通）
│
├── templates/ # 成果物テンプレート
│ ├── 010_requirements_template.html # 要件定義書
│ ├── 020_basic_design_template.html # 基本設計書
│ ├── 030_detail_design_template.html # 詳細設計書
│ ├── UAT_template.html # 受け入れテスト仕様書
│ ├── feature_request.md
│ ├── bug_report.md
│ ├── task_ticket.md
│ └── tech_debt_refactor.md
│
├── phase_gates.md # 各フェーズの完了条件（全16フェーズ）
└── settings.json # hooks設定
phase_gates.md が全体の品質を守る要。全16フェーズに「完了条件テーブル」があり、エージェントは作業前にこのファイルを読んで自分の担当フェーズの完了条件を確認する義務がある。
mainマージ＝Issue完了ではない。Phase 14（デプロイ）完了＝Issue完了。
この設計で感じた変化
| Before | After | |
|---|---|---|
| 進め方 | まとめて一気に | 1Issueずつ・会話を分けて |
| 整合性 | どこかが必ず壊れる | 設計書に追従する |
| 完了基準 | テストが通った | 自分が触れる状態 |
| 制御 | Claudeに委ねる | hooksで物理的に強制 |
| 失敗の追跡 | なぜ壊れたか分からない | どこを変えたか追える |
最大の教訓
開発ログを見返すと、この言葉が残っていた。
「省略は節約ではなく全損リスク」
Claudeが工程を省略するたびに、後から何倍もかかる修正が発生した。
そして省略したのは「Claudeが悪い」ではなく、省略できる構造にしていた設計が悪かった。
これ、人間の組織論と同じだった
hooksの話をしていて気づいたことがある。
人間の組織でも同じことが起きる。
新人が入ったとき、「ちゃんと説明したから大丈夫」と思っていると、やらかす。ベテランでも、30案件こなしているうちに手を抜き始める。人でガードしていると、必ず穴が開く。
だから組織は「仕組み」で再発防止する。
| 人間組織の問題 | 対策 | Claudeでの対応 |
|---|---|---|
| 新人がルールを守らない | 承認フローを必須にする | hooksで次フェーズをブロック |
| 慣れてくると手を抜く | チェックリストを義務化する | phase_gates.mdで完了条件を強制 |
| 担当者が越権行為をする | 権限を役割で分ける | agentのtools制限で構造的に禁止 |
| 口頭指示が伝わらない | 手順書・設計書に落とす | 設計書（HTML）を先に作り、それ通りに実装 |
| 一人に全部任せると崩れる | チームで役割分担する | マルチエージェントで分離 |
Claudeが30Issueでやらかしたのも、「ルールを知っているはずだから大丈夫」と思っていたからだった。
「人を信じるな、仕組みを作れ」は、Claudeにも完全に当てはまる。
そう考えると、今回やっていることは「AI開発」というより「AI組織のマネジメント設計」に近い。
5週間で学んだことを一言で言うと：
Claudeは組織としてマネジメントするもの。一人のAIに全部任せるものじゃない。
やっていること：
- agentで役割を分離する（commandではなくagentで各担当を動かす）
- toolsでできないことを構造的に作る（権限の制限）
- hooksで「勝手に進む」を物理的に止める（exit 2でブロック）
- 1 Issue = 1 会話を技術的に強制する（フラグファイル＋ブロック）
- 設計書を先に固め、それ通りに実装させる（その場判断を排除）
- 「触れる状態」になって初めて完了（テストPASS≠完了）
最後に：「AIは速い」を忘れたほうがいい
一つ、付け加えたいことがある。
「AI駆動開発は速い」という話をよく聞く。それは本当だと思う。でも「人間より速い」という意味であって、「機械だから一瞬」ではない。
今も1つのIssueに長いときは5時間ぐらい動き続けることがある。でも人間がやれば4〜5日かかる作業をやってくれる。その意味では圧倒的に速い。
「機械だから1〜2分で終わるはず」という期待値で使い始めると、必ず崩壊する。
なぜかというと、Claudeは放っておくとCDを最小化しようとする。時間もトークンも節約しようとする。それがQの崩壊につながる。
人間側までCDに舵を切ると、一気に品質が崩れる。
むしろ逆の意識が必要だと思っている。
時間とトークンは無駄にしまくる意識で使う。
QはClaudeが自分では守れない。だから人間が構造で守る。そのためにはCDを犠牲にすることを厭わない。
大きな案件でAIを使うなら、この覚悟が必要だと5週間で学んだ。
AI開発で一番危険だと感じているのは、
「なんとなく動いている状態」
Claudeは「早く・安く」は最強。でも「品質」は外から構造で与えないと守られない。
それを防ぐために、制御する・分割する・設計を先に作る、という構成にしている。
まだ途中だけど、壊れ方が変わった。「なぜ壊れたか分からない」から「ここを変えたからここが壊れた」が追えるようになってきた。
同じ立場の人がいれば参考になれば。
40代・非エンジニア・中間管理職。80要件の案件管理ダッシュボードを5週間検証中。