AIコーディングの本質は「プロンプト」ではなく「仮想開発組織」を作ることだった —— Tokenmaxxing / gstack / Claude Code Skills 実践入門
はじめに
AIコーディングを使っていると、だいたい最初はこうなる。
「この機能作って」
「このバグ直して」
「この画面いい感じにして」
すると、それなりに動くものは出てくる。
でも、しばらく使うと別の問題が出てくる。
- なんとなく動くが、設計が怪しい
- テストが薄い
- 同じ指示を何度も貼っている
- AIが自信満々に嘘をつく
- バグ修正でさらにバグを増やす
- レビューすると「いや、そこじゃない」となる
- 一回の成功が次回に再現されない
ここで多くの人は「もっと良いプロンプト」を探し始める。
しかし、最近のAIコーディングの本質はたぶんそこではない。
プロンプト職人になることではなく、AIを動かす開発プロセスそのものを設計すること。
もっと言うと、
AIを“一人の万能アシスタント”として使うのではなく、CEO、PM、Tech Lead、Reviewer、QA、Security、Release Engineerを持つ“仮想開発組織”として運用すること。
この考え方を強烈に体現しているのが、Y CombinatorのGarry Tan氏が公開している gstack と、そこで語られている Tokenmaxxing 的な開発スタイルです。
gstack は、Claude Code上で /office-hours, /plan-ceo-review, /plan-eng-review, /review, /qa, /ship, /cso, /investigate などの役割別Skillを使い、AIコーディングを「設計 → 実装 → レビュー → QA → リリース → 学習」の流れに押し込む仕組みです。GitHub READMEでは、Garry Tan氏のClaude Codeセットアップとして、CEO、Designer、Eng Manager、Release Manager、Doc Engineer、QAなどの役割を持つ23のツール群と説明されています。(GitHub)
Anthropic公式のClaude Code Docsでも、Skillは SKILL.md に手順を書き、/skill-name で直接呼び出せる仕組みとして説明されています。特に「同じチェックリストや複数ステップ手順を何度も貼るならSkill化せよ」という思想が明確です。(Claude)
この記事では、単なる紹介ではなく、今日から自分のリポジトリに導入できる再現可能な手順としてまとめます。
対象読者
この記事は、以下のような人向けです。
- Claude Code / Cursor / Codex / Devin / Windsurf などを使っている
- AIにコードを書かせているが、品質が不安
- AIの出力が再現不能で困っている
- テストやレビューまでAIに巻き込みたい
- 個人開発や小規模チームの開発速度を上げたい
- 「Vibe Coding」の次に何をすべきか知りたい
- AI時代の開発組織・QA・設計プロセスに興味がある
逆に、この記事は「魔法のプロンプト集」ではありません。
この記事の主張はシンプルです。
AI開発の勝ち筋は、プロンプトではなくプロセスである。
1. Tokenmaxxingとは何か
Tokenmaxxing を雑に言うと、こうです。
重要な仕事には、AIのトークンをケチらず大量投入する。
ただし、コード生成だけではなく、調査・設計・反証・テスト・レビュー・QAに使う。
ここで大事なのは、ただ長いプロンプトを書くことではないという点です。
Tokenmaxxingの本質は、以下です。
- 1つのソースで妥協しない
- 1つの実装案で妥協しない
- 1つのAIの結論で妥協しない
- 1つのテストだけで妥協しない
- 1回の成功を属人化せず、Skill化する
YC公式の Tokenmaxxing: How Top Builders Use AI To Do The Work Of 400 Engineers でも、トップビルダーがAIを使って大量の作業を進める文脈でTokenmaxxingが紹介されています。(Y Combinator)
ただし、ここで誤解してはいけません。
悪いTokenmaxxing
- とにかくAIに全部丸投げする
- 何万行もコードを書かせて満足する
- テストなしで進める
- 生成結果をレビューしない
- 仕様が曖昧なまま実装させる
- AIが詰まったら、さらに雑に「直して」と言う
これはTokenmaxxingではなく、ただの暴走です。
良いTokenmaxxing
- 実装前に課題を再定義する
- コードを書く前に設計図を描かせる
- 失敗モードを先に洗い出す
- テストマトリクスを作る
- 別のAI視点でレビューする
- Playwright等で実ブラウザQAする
- 失敗をCLAUDE.mdやSKILL.mdに戻す
つまり、
トークンは“コードを書くため”だけではなく、“間違ったコードを書かないため”に燃やす。
これが核心です。
2. AIコーディングは3段階に進化する
AIコーディングの使い方は、おおむね3段階あります。
Level 1: Chat型
User:
この関数を直して
AI:
修正案はこちらです
最初はこれで十分です。
ただし、再現性がありません。
Level 2: Agent型
User:
このIssueを見て、関連ファイルを調査して、実装して、テストして
AI:
リポジトリを読み、ファイルを編集し、テストを実行します
Claude CodeやCursor Agentなどの世界です。
かなり便利ですが、まだ危険です。
なぜなら、AIは「作ること」に最適化されがちだからです。
Level 3: Virtual Engineering Org型
/office-hours
↓
/plan-ceo-review
↓
/plan-eng-review
↓
implementation
↓
/review
↓
/qa
↓
/cso
↓
/ship
↓
/retro
これが本記事の中心です。
AIを一人の作業者ではなく、役割分離された仮想開発組織として扱います。
gstack のドキュメントでも、/office-hours はプロダクトの前提を問い直し、/plan-eng-review はアーキテクチャ、データフロー、状態遷移、失敗モード、エッジケース、テストカバレッジを扱い、/review はCIを通るが本番で壊れるバグを探し、/qa はアプリをテストしてバグを修正し回帰テストを生成する、という役割分担が説明されています。(GitHub)
3. 最小構成：まず何を用意すべきか
まず、リポジトリに以下を置きます。
repo/
CLAUDE.md
docs/
product/
vision.md
user-personas.md
customer-pain.md
architecture/
system-overview.md
data-flow.md
api-contracts.md
quality/
test-strategy.md
qa-checklist.md
known-failures.md
decisions/
adr-0001-example.md
retros/
2026-05-12-retro.md
.claude/
skills/
office-hours-ja/
SKILL.md
tokenmax-research-ja/
SKILL.md
plan-eng-review-ja/
SKILL.md
review-ja/
SKILL.md
qa-ja/
SKILL.md
investigate-ja/
SKILL.md
ship-ja/
SKILL.md
retro-ja/
SKILL.md
役割はこうです。
| ファイル / ディレクトリ | 役割 |
|---|---|
CLAUDE.md |
AIが常に知るべき恒久ルール |
.claude/skills/*/SKILL.md |
再利用可能な手順 |
docs/product |
プロダクト思想 |
docs/architecture |
技術設計 |
docs/quality |
テスト・QA |
docs/decisions |
意思決定ログ |
docs/retros |
振り返り・学習 |
ポイントは、AIに毎回説明しないことです。
人間の開発組織でも、新人に毎回口頭説明していたら破綻します。
AIにもオンボーディング資料と標準作業手順書が必要です。
4. CLAUDE.mdに書くべきこと
CLAUDE.md は、AIに常時読ませる「プロジェクト憲法」です。
# CLAUDE.md
## Project
このプロジェクトは {{プロダクト名}} です。
## Product Goal
{{誰の、どんな課題を、どう解決するか}}
## Core Principles
- 実装前に必ず既存コードを読む
- 計画外の変更をしない
- テストなしでビジネスロジックを変更しない
- セキュリティ・認可・課金・計算ロジックは人間確認を求める
- 破壊的コマンドは禁止
- 推測で仕様を補完しない
- 不明点は Unknown として明示する
## Architecture Rules
- API contractを壊す場合は docs/architecture/api-contracts.md を更新する
- DB schema変更時は migration と rollback plan を書く
- 外部API連携では timeout, retry, error handling を明示する
- tenant boundary を越えるデータアクセスは禁止
## Testing Rules
- 新規ロジックには unit test を追加する
- 主要フローには integration test を追加する
- UI変更には Playwright E2E を追加する
- バグ修正時は regression test を追加する
## Documentation Rules
- 仕様変更時は docs/ を更新する
- 重要な意思決定は docs/decisions/ にADRとして残す
- 失敗や学びは docs/retros/ に残す
CLAUDE.md には「手順」よりも「恒久的ルール」を書きます。
一方で、長い手順やチェックリストはSkillに逃がします。
Anthropic公式ドキュメントでも、Skillは SKILL.md に手順を書き、必要なときだけ読み込まれる仕組みとして説明されています。長い手順や参照資料は、常時コンテキストに入れるのではなくSkill化する方が合理的です。(Claude)
5. Skillの基本構造
Claude CodeのSkillは、基本的にこういう構造です。
.claude/skills/
skill-name/
SKILL.md
SKILL.md の最小例はこれです。
---
description: Use this skill when you need to review implementation plans before writing code.
---
# Role
You are a strict engineering manager.
# Goal
Review the proposed implementation before any code is written.
# Process
1. Read the user's request
2. Inspect the existing codebase
3. Identify affected files
4. Draw the architecture
5. List edge cases
6. Create a test matrix
7. Identify security risks
8. Produce an implementation plan
# Output Format
- Architecture Summary
- ASCII Diagrams
- File Impact Map
- Edge Cases
- Test Matrix
- Risks
- Implementation Plan
- Approval Gates
ここで重要なのは、Skillは「プロンプト」ではなく手順書だということです。
プロンプトは一回限りの命令。
Skillは繰り返し使える工程資産です。
6. 標準ワークフロー
1機能を作るときの標準フローはこれです。
Issue
↓
/office-hours-ja
↓
/tokenmax-research-ja
↓
/plan-eng-review-ja
↓
Implementation
↓
/review-ja
↓
/qa-ja
↓
/investigate-ja
↓
/ship-ja
↓
/retro-ja
図にするとこうです。
[Human / Product Owner]
|
v
[Office Hours: 課題再定義]
|
v
[Research: 事実確認・反証]
|
v
[Engineering Plan: 設計・テスト計画]
|
v
[Implementation Agent]
|
v
[Staff Engineer Review]
|
v
[Browser QA / Playwright]
|
v
[Debug / Root Cause]
|
v
[Ship / PR / Release]
|
v
[Retro / Skill Update]
|
└──────> 次回さらに賢くなる
大事なのは、AIを「実装」から始めないことです。
7. Step 1: /office-hours-ja で課題を再定義する
AI開発で一番危険なのは、間違ったものを高速に作ることです。
だから最初にやるべきは実装ではなく、問い直しです。
ユーザーは本当にその機能が欲しいのか？
それとも、その機能で解決したい別の痛みがあるのか？
.claude/skills/office-hours-ja/SKILL.md
---
description: Use this skill before planning or implementing a new feature. It reframes the user's request, challenges assumptions, and finds the smallest valuable wedge.
---
# Role
あなたはYC Office Hoursのパートナーです。
ユーザーの依頼をそのまま実装してはいけません。
# Goal
機能要求の背後にある本当の顧客課題を見つけ、より小さく、より価値の高い実装に再定義します。
# Process
1. ユーザーの要求を一文で要約する
2. 背後にある顧客課題を抽出する
3. 要求に含まれる誤った前提を指摘する
4. より小さく検証できる実装案を3つ出す
5. 10倍価値になる方向性を出す
6. 今回やらないことを明確にする
7. 実装前に確認すべき質問を最大5つに絞る
# Output Format
## Request Summary
## Hidden Customer Pain
## Wrong Assumptions
## Three Smaller Implementation Paths
## Narrowest Valuable Wedge
## 10x Opportunity
## Non-goals
## Questions Before Implementation
使い方
/office-hours-ja
販売代理店が、住宅用太陽光・蓄電池・V2Hの提案時に、
対象自治体の補助金有無・金額・期限・併用可否をすぐ確認できる機能を作りたい。
期待する出力は、たとえばこうです。
あなたが作りたいのは「補助金検索機能」ではなく、
販売代理店が誤提案リスクを下げ、根拠付き提案書を速く作るための機能です。
最小Wedge:
- 自治体名
- 設備種別
- 補助金名
- 金額
- 期限
- 出典URL
- 最終確認日
- 確信度
だけを出す。
10x Opportunity:
- 提案書への根拠付き自動挿入
- 併用可否の自動判定
- 古い制度情報の警告
- 顧客向け説明文の生成
この段階で、作るものが変わります。
8. Step 2: /tokenmax-research-ja で調査を沸騰させる
制度、料金、仕様、競合、法規制、API、セキュリティ。
こういう領域でAIに1ソースだけ見せて判断させるのは危険です。
Tokenmaxxingすべきです。
.claude/skills/tokenmax-research-ja/SKILL.md
---
description: Use this skill when a decision depends on external facts, regulations, market data, technical docs, pricing, APIs, or rapidly changing information.
---
# Role
あなたは厳格なResearch Analystです。
# Goal
意思決定に使える事実を、一次情報・複数ソース・反証込みで整理します。
# Rules
- 一次情報を最優先する
- URLを必ず付ける
- 日付を確認する
- 古い情報と新しい情報を分ける
- 推測と事実を分ける
- 反対証拠を探す
- 重要主張ごとに信頼度を付ける
- 不明点を Unknown として明示する
- 可能なら20ソース以上を比較する
# Process
1. 調査テーマを定義する
2. 意思決定に必要な問いを分解する
3. 一次情報を探す
4. 二次情報で補完する
5. 矛盾する情報を探す
6. 事実と推測を分ける
7. 意思決定への示唆を出す
8. 追加調査すべき論点を出す
# Output Format
## Executive Summary
## Decision-Relevant Facts
## Source Table
| # | Source | URL | Date | Claim | Evidence Type | Confidence | Notes |
|---|---|---|---|---|---|---|---|
## Conflicting Evidence
## Unknowns
## Risks
## Recommendation
## Follow-up Questions
ここでのポイントは、AIに「調べて」と言わないことです。
悪い:
補助金について調べて
良い:
住宅用蓄電池の自治体補助金について、
提案書に掲載してよい粒度で、
出典URL・更新日・併用可否・不確実性を整理して
9. Step 3: /plan-eng-review-ja で設計図を描かせる
AIにコードを書かせる前に、必ず設計図を描かせます。
なぜなら、LLMは文章だけだと局所最適に走りやすいからです。
gstack のドキュメントでも、/plan-eng-review ではアーキテクチャ、システム境界、データフロー、状態遷移、失敗モード、エッジケース、信頼境界、テストカバレッジを扱い、図を描かせることが隠れた前提を表に出す大きなアンロックだと説明されています。(GitHub)
.claude/skills/plan-eng-review-ja/SKILL.md
---
description: Use this skill before implementation. It creates architecture diagrams, file impact maps, edge cases, test matrices, and approval gates.
---
# Role
あなたは厳格なEngineering Managerです。
まだコードを書いてはいけません。
# Goal
実装前に、設計、依存関係、データフロー、エラー経路、テスト計画を明確にします。
# Process
1. ユーザー要求を要約する
2. 既存コードと関連ドキュメントを読む
3. 変更対象ファイルを列挙する
4. ユーザーフローをASCIIで描く
5. データフローをASCIIで描く
6. 状態遷移をASCIIで描く
7. エラー経路をASCIIで描く
8. 権限境界と信頼境界を明示する
9. エッジケースを最低20個出す
10. テストマトリクスを作る
11. セキュリティリスクを出す
12. 実装ステップを小さく分解する
13. 人間承認が必要なポイントを明示する
# Output Format
## Requirement Summary
## Existing System Understanding
## User Flow
## Data Flow
## State Machine
## Error Paths
## Trust Boundaries
## File Impact Map
## Edge Cases
## Test Matrix
| Layer | Scenario | Expected Result | Test Type |
|---|---|---|---|
## Security Concerns
## Implementation Plan
## Human Approval Gates
## Stop Conditions
ASCII図の例
[User]
|
v
[Frontend Form]
|
| validate input
v
[API: /api/simulations]
|
| auth + schema validation
v
[Simulation Service]
|
| fetch tariff / subsidy data
v
[Calculation Engine]
|
v
[Result DTO]
|
v
[Frontend Result View]
|
v
[Export / Save / Share]
これをやるだけで、AIの理解度がかなり変わります。
コードを書く前に、AIの頭の中を可視化する。
これが重要です。
10. Step 4: 実装は小さく、原子的に進める
設計が終わったら実装します。
ただし、一気に全部やらせない。
悪い:
この計画を全部実装して
良い:
Step 1だけ実装して。
変更ファイル、理由、追加テスト、リスクを報告して。
計画外の変更は禁止。
実装時の基本ルールはこうです。
- 1 commit = 1意味単位
- 1 PR = 1機能または1明確な改善
- 計画外の変更は禁止
- テストなしのビジネスロジック変更は禁止
- 課金・認可・計算・セキュリティは人間確認
実装用プロンプト
承認済みのImplementation Planに従って、Step 1だけ実装してください。
ルール:
- 計画外の変更は禁止
- 1ステップだけ実装
- 既存テストを壊したら停止
- 新規ロジックにはテストを追加
- 型エラー、lint、test失敗を放置しない
出力:
- Changed files
- Why changed
- Tests added
- Risks
- Next step
11. Step 5: /review-ja で壊す視点を入れる
実装したAIに、そのまま「レビューして」と言うのは弱いです。
人間でも、自分のコードのバグは見落とします。
AIも同じです。
レビューは、別の役割として実行します。
.claude/skills/review-ja/SKILL.md
---
description: Use this skill after implementation. It reviews the git diff for production bugs, incomplete logic, security issues, missing tests, and contract breaks.
---
# Role
あなたはStaff Engineerです。
実装者を信用しすぎてはいけません。
# Goal
CIを通るが本番で壊れる問題を見つけます。
# Inputs
- git diff
- changed files
- tests
- docs
- existing architecture
# Review Checklist
1. 本番で壊れるバグ
2. CIでは検出されないバグ
3. race condition
4. null / undefined / boundary values
5. API contract破壊
6. 認証・認可の漏れ
7. tenant isolationの破壊
8. injection risk
9. XSS / CSRF
10. 外部API失敗時の挙動
11. timeout / retry
12. rollback困難性
13. UX劣化
14. テスト不足
15. ドキュメント更新漏れ
# Output Format
## Summary
## Must Fix
## Should Fix
## Nice to Have
## Missing Tests
## Security Concerns
## Production Risks
## Ship Decision
PASS / HOLD
レビューの合格条件
- Must Fixが0件
- Security Highが0件
- ビジネスロジックにテストがある
- API変更時にドキュメント更新がある
- ロールバック方法がある
特に重要なのはこの問いです。
この変更は、CIを通るのに本番で壊れるとしたら、どこか？
これはかなり効きます。
12. Step 6: /qa-ja でブラウザを実際に踏ませる
コードレビューだけでは不十分です。
Webアプリなら、最後はブラウザで踏む必要があります。
gstack の /qa は、アプリをテストし、バグを見つけ、修正し、再検証し、修正ごとに回帰テストを生成する役割として説明されています。(GitHub)
.claude/skills/qa-ja/SKILL.md
---
description: Use this skill after implementation and review. It performs browser-based QA, finds bugs, records reproduction steps, and proposes regression tests.
---
# Role
あなたはQA Leadです。
コードではなく、ユーザー体験として検証します。
# Goal
実ブラウザ操作に近い観点で、主要フローとエッジケースを検証します。
# QA Checklist
1. Happy path
2. 入力不備
3. 権限なし
4. セッション切れ
5. ネットワーク失敗
6. 外部API失敗
7. 境界値
8. 大量データ
9. モバイル幅
10. 戻る・更新
11. 二重送信
12. 表示崩れ
13. エラーメッセージ
14. アクセシビリティ
15. パフォーマンス
16. 回帰
# Process
1. 対象フローを特定する
2. テストシナリオを作る
3. 実ブラウザまたはPlaywrightで検証する
4. バグを再現手順付きで記録する
5. 修正案を出す
6. 修正後に再検証する
7. regression testを提案する
# Output Format
## Tested Scenarios
## Bugs Found
## Reproduction Steps
## Screenshots / Evidence
## Fix Suggestions
## Regression Tests
## Remaining Risks
## QA Decision
PASS / HOLD
Playwrightの最小例
import { test, expect } from '@playwright/test';
test('user can create simulation and view result', async ({ page }) => {
await page.goto('/simulations/new');
await page.getByLabel('Customer name').fill('Test Customer');
await page.getByLabel('Monthly electricity bill').fill('30000');
await page.getByRole('button', { name: 'Calculate' }).click();
await expect(page.getByText('Simulation Result')).toBeVisible();
await expect(page.getByText('Estimated savings')).toBeVisible();
});
AIにコードを書かせるなら、AIにブラウザも触らせるべきです。
13. Step 7: /investigate-ja で「推測修正」を禁止する
AIがバグ修正で危険なのは、証拠なしに直し始めることです。
User:
まだ壊れてる。直して。
AI:
別の箇所を直しました。
User:
まだ壊れてる。
AI:
さらに別の箇所を直しました。
これを繰り返すと、コードベースが壊れます。
gstack の /investigate も、根本原因調査を重視し、「no fixes without investigation」という方針や、データフロー追跡、仮説検証、3回失敗したら止まる流れが説明されています。(GitHub)
.claude/skills/investigate-ja/SKILL.md
---
description: Use this skill when debugging. It forbids fixes before investigation, traces data flow, tests hypotheses, and stops after repeated failed attempts.
---
# Role
あなたはDebuggerです。
まだ修正してはいけません。
# Iron Rule
No fixes without investigation.
# Process
1. バグを一文で要約する
2. 再現手順を書く
3. 期待値と実際値を分ける
4. 関連コードを読む
5. データフローをASCIIで描く
6. 仮説を最低3つ出す
7. 各仮説の検証方法を書く
8. 最も可能性が高い仮説から検証する
9. 証拠が出た仮説だけ修正する
10. 修正後にregression testを追加する
11. 3回失敗したら停止する
# Output Format
## Bug Summary
## Reproduction
## Expected vs Actual
## Data Flow
## Hypotheses
| # | Hypothesis | Evidence Needed | How to Test |
|---|---|---|---|
## Evidence
## Root Cause
## Minimal Fix
## Regression Test
## Stop / Continue Decision
このSkillは本当に重要です。
AIにバグを直させるときは、まずこう言うべきです。
/investigate-ja
まだ修正しないで。
再現条件、期待値、実際値、データフロー、仮説、検証方法を出して。
証拠が出るまでコードを変更しないで。
14. Step 8: /ship-ja でPRとリリースを標準化する
最後に、リリースもAIに雑にやらせない。
.claude/skills/ship-ja/SKILL.md
---
description: Use this skill when preparing a pull request or release. It checks tests, coverage, docs, risks, rollback plan, and writes a PR description.
---
# Role
あなたはRelease Engineerです。
# Goal
安全にPRを作成し、レビュー可能な形でリリース準備を整えます。
# Process
1. mainとの差分を確認する
2. 変更内容を要約する
3. test / lint / typecheckを実行する
4. coverageを確認する
5. docs更新漏れを確認する
6. スクリーンショットや証跡を整理する
7. リスクを列挙する
8. rollback planを書く
9. PR本文を作る
10. リリース後確認項目を書く
# Output Format
## Summary
## Customer Value
## Technical Changes
## Tests
## Evidence
## Risks
## Rollback Plan
## Post-release Checklist
## PR Body
PRテンプレート
## Summary
## Customer Value
## Technical Changes
## Tests
- [ ] Unit tests
- [ ] Integration tests
- [ ] E2E tests
- [ ] Manual QA
- [ ] Security review
## Evidence
## Risks
## Rollback Plan
## Post-release Checklist
これを毎回やるだけで、AIが書いたコードの「出荷品質」がかなり上がります。
15. Step 9: /retro-ja で失敗をSkillに戻す
ここが一番大事です。
AI活用が下手なチームは、毎回同じ失敗をします。
- またテストが薄い
- また認可漏れ
- また外部API失敗時の処理がない
- またREADMEが古い
- また計算ロジックの境界値が抜けている
AI活用が上手いチームは、失敗を手順に戻します。
失敗
↓
原因分析
↓
CLAUDE.md更新
↓
SKILL.md更新
↓
次回から自動チェック
.claude/skills/retro-ja/SKILL.md
---
description: Use this skill after shipping or after a failed implementation. It extracts lessons and updates project rules, skills, tests, and documentation.
---
# Role
あなたはEngineering Managerです。
# Goal
今回の開発から学びを抽出し、次回の品質と速度を上げるために手順へ反映します。
# Process
1. 今回の目的を要約する
2. 何がうまくいったかを整理する
3. 何が遅かったかを整理する
4. AIが迷った箇所を整理する
5. バグや手戻りの根本原因を整理する
6. 不足していたテストを整理する
7. CLAUDE.mdに追加すべきルールを出す
8. SKILL.mdに追加すべき手順を出す
9. docsに追加すべき仕様を出す
10. 次回から禁止すべきパターンを出す
# Output Format
## What Worked
## What Failed
## AI Confusion Points
## Root Causes
## Missing Tests
## Update CLAUDE.md
## Update SKILL.md
## Update Docs
## New Guardrails
## Next Action
このループを回すと、AIは単なるツールではなく、組織の学習装置になります。
16. Fat Skills / Thin Harness という考え方
ここで、自分が重要だと思う概念があります。
Fat Skills / Thin Harness
つまり、
- ツール連携は薄くする
- 手順と判断基準はSkillに厚く書く
悪い例。
巨大な自作ツールを作る
↓
メンテ不能になる
↓
AIの進化に追従できない
良い例。
Git, GitHub, Playwright, test runner, CI などは既存ツールを使う
↓
AIへの指示・判断基準・チェックリストをSkill化する
↓
モデルやツールが変わっても手順資産が残る
AI時代の開発資産は、コードだけではありません。
- Skill
- Checklist
- Test Matrix
- Failure Pattern
- ADR
- QA Scenario
- Prompted Workflow
- Human Approval Gate
これらが、新しい意味での「開発組織の知識資産」になります。
17. なぜASCII図が効くのか
AIに設計させるとき、個人的に最も効くのはASCII図です。
[User]
|
v
[Frontend]
|
v
[API]
|
v
[Service]
|
v
[DB]
一見しょぼく見えます。
でも、これを描かせるとAIは以下を明示せざるを得ません。
- 入力はどこから来るか
- データはどこを通るか
- 誰が認可するか
- どこでバリデーションするか
- どこで失敗するか
- どこをテストすべきか
LLMは文章だけだと曖昧さを抱えたまま進めます。
図にすると、曖昧さが表に出ます。
状態遷移図の例
[Draft]
|
| submit
v
[Running]
|
| success
v
[Completed]
[Running]
|
| error
v
[Failed]
[Failed]
|
| retry
v
[Running]
エラー経路の例
[User Input]
|
| invalid
v
[Validation Error]
[API Request]
|
| unauthorized
v
[401 Unauthorized]
[External API]
|
| timeout
v
[Retry Queue]
[Calculation Engine]
|
| invalid tariff
v
[Result Requires Manual Review]
このレベルまで描かせてから実装すると、品質が変わります。
18. AI開発における役割分離
AIを1人格で使うと、自己正当化が起きます。
だから、役割を分けます。
| 役割 | やること |
|---|---|
| Office Hours | 問い直す |
| CEO / Founder | 価値判断する |
| Researcher | 事実確認する |
| Engineering Manager | 設計する |
| Engineer | 実装する |
| Staff Engineer | 壊す視点でレビューする |
| QA Lead | ユーザーとして踏む |
| Security Officer | 脅威を見る |
| Release Engineer | 安全に出す |
| Retro Manager | 学習を残す |
同じモデルでも、別セッション・別Skill・別役割にするだけで効果があります。
さらに強くするなら、複数モデルを使います。
Claude Code:
設計・実装
Codex:
第二意見・コードレビュー
Gemini:
長文資料・仕様読解
Playwright:
実ブラウザQA
Human:
意思決定・味・責任
AI時代の開発者は、コードを書く人というより、AI開発組織の編成者になります。
19. アンチパターン
アンチパターン1: 「全部作って」
この機能全部作って
これは危険です。
代わりに、
まだコードを書かないで。
まず設計図、変更ファイル、エッジケース、テストマトリクスを出して。
アンチパターン2: テストを後回しにする
AI開発では、テストは後工程ではありません。
設計工程です。
設計
↓
テストマトリクス
↓
実装
↓
テスト
この順番にするべきです。
アンチパターン3: AIに自分の実装をレビューさせる
同じ流れでそのままレビューさせると、見落としやすいです。
実装AI
↓
別SkillのレビューAI
↓
別観点のQA AI
に分けるべきです。
アンチパターン4: バグ修正で推測を重ねる
直して
まだ直ってない
もう一回直して
これはコードベースを破壊します。
再現
期待値
実際値
データフロー
仮説
証拠
最小修正
回帰テスト
の順に進めます。
アンチパターン5: LOCを成果指標にする
AI時代に「何万行書いた」は危険な虚栄指標です。
本当に見るべき指標はこっちです。
- 顧客価値
- 出荷速度
- 本番バグ率
- 回帰テスト数
- レビュー差し戻し率
- 仕様変更への追従速度
- Skill再利用率
- 同じ失敗の再発率
20. 実務で使うメトリクス
AIコーディングを本気で運用するなら、以下を測るとよいです。
開発速度
- Issue作成からPRまでの時間
- PR作成からmergeまでの時間
- 1週間あたりの出荷数
- 1機能あたりのAI利用コスト
品質
- test coverage
- E2E pass rate
- QAで検出したバグ数
- 本番障害数
- rollback回数
- regression test追加数
AI運用品質
- Skill使用回数
- Skill更新回数
- 同じ失敗の再発率
- 人間レビューでのMust Fix件数
- AIが詰まった回数
- 3回以上修正失敗した件数
事業価値
- 顧客の作業時間削減
- 提案・見積・調査のリードタイム短縮
- 成約率
- 解約率
- API利用量
- サポート問い合わせ削減
AI導入の目的は、開発者が楽をすることだけではありません。
顧客価値を速く、正確に、継続的に届けることです。
21. 今日からやるなら、この順番
いきなり全部作らなくていいです。
まずはこれだけで十分です。
Day 1
CLAUDE.mdを書く
最低限これを書く。
- プロダクトの目的
- 技術スタック
- 禁止事項
- テスト方針
- セキュリティ方針
Day 2
/plan-eng-review-ja を作る
コードを書く前に設計図を描かせる。
Day 3
/review-ja を作る
CIを通るが本番で壊れる問題を探させる。
Day 4
/qa-ja を作る
PlaywrightやブラウザQAを入れる。
Day 5
/investigate-ja を作る
推測修正を禁止する。
Day 6
/retro-ja を作る
失敗をSkillに戻す。
Day 7
1つの小さな機能で、最初から最後まで回す。
Issue
→ Office Hours
→ Eng Review
→ Implementation
→ Review
→ QA
→ Ship
→ Retro
これで、AIコーディングは「便利ツール」から「開発OS」に変わります。
22. 最小テンプレまとめ
最後に、最小構成を貼っておきます。
ディレクトリ作成
mkdir -p .claude/skills/office-hours-ja
mkdir -p .claude/skills/plan-eng-review-ja
mkdir -p .claude/skills/review-ja
mkdir -p .claude/skills/qa-ja
mkdir -p .claude/skills/investigate-ja
mkdir -p .claude/skills/ship-ja
mkdir -p .claude/skills/retro-ja
mkdir -p docs/product
mkdir -p docs/architecture
mkdir -p docs/quality
mkdir -p docs/decisions
mkdir -p docs/retros
最初のCLAUDE.md
# CLAUDE.md
## Core Rules
- Do not implement before reading existing code.
- Do not make unrelated changes.
- Do not change business logic without tests.
- Do not modify auth, billing, tenant isolation, or security-sensitive code without explicit approval.
- Always add regression tests for bug fixes.
- Always separate facts, assumptions, and unknowns.
- Stop after 3 failed fix attempts and investigate root cause.
## Output Rules
For implementation steps, always report:
- Changed files
- Why changed
- Tests added
- Risks
- Next step
最初に作るべきSkill
plan-eng-review-ja
review-ja
qa-ja
investigate-ja
まずこの4つだけでいいです。
23. 結論
AIコーディングの本質は、たぶん「AIにコードを書かせること」ではありません。
本質は、
人間が意思決定し、
AIに設計させ、
AIに実装させ、
AIに壊させ、
AIにブラウザで踏ませ、
AIに学習を残させる。
ことです。
つまり、
AIを作業者として使うのではなく、再現可能な開発組織として設計する。
これから強いエンジニアは、単にコードが書ける人ではなくなると思います。
強いエンジニアは、
- 問いを設計できる
- AIの役割を分離できる
- 検証工程を組める
- 失敗を手順化できる
- 品質をプロセスに埋め込める
- 人間が判断すべき場所を見極められる
人です。
そして、これは個人開発でもチーム開発でも使えます。
最後に、この考え方を一文に圧縮します。
トークンをケチるな。ただし、コード生成だけに燃やすな。設計、反証、レビュー、QA、学習に燃やせ。
AI時代の開発速度は、プロンプトの上手さではなく、
どれだけ強い開発プロセスをAIに持たせられるかで決まります。