AI Slop(AIによって大量に生成された、品質の低いコンテンツやコード)を最も手っ取り早く作る方法は、AIエージェントを起動して、次のように指示することです。
「友人同士の旅行費用を割り勘するアプリを作ってください。」
10分後には、ダークモードまで備えた、見た目の良いアプリが完成します。しかし3日後には、誰も、そしてAI自身でさえ、なぜ100,000円を3人で割ると合計が99,999円になるのか説明できないコードベースが残ります。さらに、1か所を修正するたびに別の2か所が壊れるようになります。
問題はモデルそのものではありません。
開発を始める前に、覚えておきたい研究結果が2つあります。
- METR が2025年に実施した対照実験では、16人の経験豊富なオープンソース開発者が、自分たちが普段開発しているリポジトリ上で246件の実作業を行いました。その結果、AIを使用した場合、作業速度は約19%低下しました。一方、開発者自身は約20%速くなったと感じていました。ただし、研究チームは結果の一般化には注意が必要だとしています。対象は大規模で、開発者が熟知しているリポジトリであり、使用されたツールも2025年初頭のものだからです。
- DORA 2025 のAIを活用したソフトウェア開発に関するレポートでは、AIは「増幅器(Amplifier)」であると結論づけています。すでに優れた開発プロセスを持つチームは、AIによってさらに成果を上げられます。一方、プロセスが整理されていないチームでは、その混乱がより速く拡大します。
つまり、重要なのは「AIを使うかどうか」ではなく、**「どのような開発プロセスでAIを使うか」**です。
この記事では、実際に開発現場で使われ、公開されている複数のワークフローを参考に、7つのステップに整理した開発プロセスを紹介します。
参考にしたのは、以下の取り組みです。
- Harper Reedによる、アイデアから仕様書、実装計画までのワークフロー:My LLM Codegen Workflow
- GitHubのSpec Kit
- Claude Code公式ドキュメントの、調査・計画・実装・コミットのワークフロー:Best Practices
- Addy OsmaniによるAIコーディングワークフロー:AI Coding Workflow
- Simon Willisonによるコードレビューの考え方:Vibe Coding
記事全体を通して、最初に挙げた「割り勘アプリ」を例に説明していきます。
各ステップには「さらに深掘り」というセクションを設け、その工程で使える具体的な技術や手法も紹介します。これらは、私が開発したClaude Code、Cursor、Codex向けのスキル集であるPrimeKitにまとめています。
最初に明確にしておきたいのですが、PrimeKitは私自身が開発したプロダクトです。そのため、各スキルの内部でどのような処理を行っているのかも説明しています。ツールをインストールしなくても、手動で、あるいは別のツールを使って同じ考え方を取り入れることができます。
試してみたい場合は、以下のコマンドでインストールできます。
npx @lovehlmmm/primekit init
インストール後、AIエージェント上で次のように呼び出します。
/pk:<skill-name>
全体像:7つのステップと、それぞれに残す成果物
1. アイデア整理 ── 対話 ──▶ spec.md
(何を作るか、誰のためか、何を作らないか)
2. 開発ルール ───────────▶ AGENTS.md
(技術スタック、規約、テストコマンド)+ lint、CI
GLOSSARY.md、ADR
(ドメイン用語、確定した意思決定)
3. 技術計画 ─────────────▶ plan.md
(データ、API、アーキテクチャ、リスク)
4. タスク分割 ───────────▶ tasks.md
(小さな作業単位、それぞれの検証方法)
edge-cases.md
(テストすべき境界条件)
5. タスクごとの開発 ─────▶ test → code → 検証 → 小さくcommit
6. レビュー ─────────────▶ 自分で1行ずつ説明できるPR
7. リリースと改善 ───────▶ 発生した不具合を自動チェックに変換
どの開発プロセスにも共通している考え方があります。
AIはコードを書く。何を作るか、何を検証するかを決めるのは人間です。
右側に示したファイルは、その意思決定が作業の途中で失われないようにするためのものです。
AIエージェントは昨日のことを覚えていないかもしれません。しかし、ファイルに残しておけば、その情報は維持できます。
Step 1:AIに質問させながら、アイデアを仕様書に落とし込む
最もよくある失敗は、AIに自分の要求を推測させてしまうことです。
Harper Reedは、このアプローチを逆転させています。
AIに要求を推測させるのではなく、仕様が十分に明確になるまで、AIから質問させるのです。
私がこの考え方をもとに作成したプロンプトは次のとおりです。
作りたいもの:
友人同士で旅行費用を割り勘するアプリ。
このアイデアを、別の開発者が実装できるほど
詳細な仕様書にするために、必ず1回に1つずつ質問してください。
各質問は1つの論点だけにしてください。
それまでの回答を踏まえて、次の質問を考えてください。
私がまだ考えていないことも確認してください。
例えば、境界条件、利用者、対象外とする機能などです。
私が「完了」と伝えたら、回答をまとめてspec.mdを作成してください。
1つずつ質問する方法は、一見すると時間がかかるように思えます。
しかし、例えば次のような質問が重要になります。
- 「支払いを済ませた人がグループを退会した場合、どうしますか?」
- 「割り切れない金額が発生した場合、余った1円は誰が負担しますか?」
こうした質問によって、自分がまだ考えていなかった仕様に気づくことができます。
最終的に、次のような簡潔な仕様書ができます。
# spec.md:グループ割り勘アプリ
## 目的
2〜20人のグループで共同支出を記録し、
誰が誰にいくら支払う必要があるかを計算する。
## ユーザー
旅行中の友人グループ。
スマートフォンで利用し、アカウント登録は不要。
## メインフロー
1. グループを作成し、招待リンクを共有する。
2. 支出を追加する。
- 誰が支払ったか
- 金額
- 誰に分配するか(均等または個別金額)
3. 「誰が誰にいくら支払うか」を表示し、
送金回数を最小限にする。
## 初期バージョンでは対応しないこと
- 決済機能との連携
- 複数通貨への対応
- 独立したモバイルアプリ
## 受け入れ基準
- 分配金額の合計は、端数が発生する場合でも
元の金額と必ず一致すること(最小単位:1円)。
- スマートフォンでの支出追加が15秒以内に完了すること。
ここで重要なのは、**「やらないこと(Out of Scope)」**を明確にすることです。
これは、Step 5でAIが「Googleログイン機能も追加しましょう」と提案してきたときに、仕様を根拠として断るためにも役立ちます。
さらに深掘り:ルールに基づいたヒアリング
「1つずつ質問する」という方法には、2つの問題が起こりがちです。
- AIが勝手に仕様を追加してしまう。
- 10個ほど質問した後にまとめて仕様書を作成するため、途中の回答を忘れてしまう。
interview-spec-extractor は、いくつかの明確なルールによって、この問題を防ぎます。
| ルール | 理由 |
|---|---|
| 質問する前に既存ドキュメントを読む | READMEなどにすでに書かれている内容を再度質問しないため |
| ドキュメントのひな形は最初に1回だけ作成し、質問は必ず1つの自由回答形式にする | 「メンバーがグループを退会した場合、どうしたいですか?」のような質問は、Yes/No形式より多くの情報を得られるため |
| 回答を受け取ったら、次の質問に進む前に該当箇所へすぐ記録する | 対話が進んでも回答が失われないため |
| ユーザーが提示した選択肢は順序のない集合として扱う。優先順位が必要な場合は必ず確認する | AIが勝手に機能の優先順位を決めないため |
| ユーザーの表現を維持し、推測による項目を追加しない | 仕様書はユーザーの意図を表すものであり、モデルの考えを表すものではないため |
さらに、後続の工程で使用する質問を整理するclarifyスキルと組み合わせます。
このスキルでは、回答によって作業の方向性が変わる場合にのみ質問します。
安全で、後から変更可能なデフォルト値がある場合は、AIが自分で選択し、その選択を明記します。
これにより、金額計算のロジックを実装している最中に、エージェントから「ボタンの色は何色にしますか?」といった質問をされることを減らせます。
Step 2:一度決めた開発ルールを、すべてのセッションで適用する
Spec Kitでは、この工程を「Constitution(憲法)」と呼んでいます。
これは、以降のすべてのコードが従わなければならない基本原則です。
実際の開発では、リポジトリのルートに配置するAGENTS.md(またはCLAUDE.md)がその役割を果たします。
AIエージェントは、各セッションの開始時にこのファイルを読み込みます。
# AGENTS.md
## Stack
- Next.js(App Router)
- TypeScript strict
- Drizzle経由でPostgreSQLを使用
## Commands
- Test: pnpm test
- Lint: pnpm lint
- Typecheck: pnpm typecheck
タスク完了を報告する前に、上記3つをすべて実行すること。
## Conventions
- 金額は整数(円)で保存する。小数を使用しない。
- 計算ロジックはsrc/domain/に配置し、
Reactやデータベースに依存させない。
- テストを通すためにテストコードを変更しない。
テストの内容が間違っている場合は確認すること。
このファイルはできるだけ短く保ちます。
各行は、AIエージェントがすべての作業で守るべきルールです。
そのため、機械的に検証できるルールは、lintルールやテストに移し、AGENTS.mdから削除するのが理想です。
これは、同シリーズのAll Code Is Slopで紹介されている「指示を決定論的なチェックに変換する」という考え方でもあります。
例えば、「計算ロジックからReactをimportしてはいけない」というルールは、ESLintのno-restricted-importsで制限できます。
そうすれば、AIの記憶に頼る必要はなく、違反した場合はCIが失敗します。
また、この段階で以下の環境も整備しておきます。
- lint
- typecheck
- テストの基本構成
- PRごとに上記3つを実行するCI
重要なのは、最初の機能コードを書く前に、これらを準備しておくことです。
さらに深掘り:ドメイン用語集と確定済みの意思決定
AIが気づかないうちに壊してしまうものが2つあります。
1つ目は、同じ概念に複数の名前を付けてしまうことです。
例えば、ある概念をファイルによってdebt、owed、balanceと呼んでしまうケースです。
2つ目は、すでに確定した設計判断を再び変更してしまうことです。
例えば、「計算を簡単にするため」という理由で、金額の型を整数から小数を含むnumberに変更してしまうケースです。
domain-modelingスキルでは、この問題を防ぐために2つのファイルを管理します。
まず、GLOSSARY.mdです。
# GLOSSARY.md
| 用語 | 意味 | コード上の名前 |
|---|---|---|
| 支出 | 誰かがグループ全体のために支払った1回の取引 | Expense |
| 分担額 | 1つの支出について、各メンバーが負担する金額 | Share |
| 残高 | 受取総額から負担総額を引いた金額。正数は受取超過、負数は支払超過 | balance |
| 精算 | すべての残高を0にするための送金一覧 | settle() |
次に、docs/adr/0001-money-as-integer.mdです。
ADR(Architecture Decision Record)は、確定した設計判断を記録するためのドキュメントです。
# docs/adr/0001-money-as-integer.md
Status: Accepted
Context:
浮動小数点数では、.5などの端数処理や累積誤差が発生する。
仕様では、分配額の合計が1円単位で正確に一致する必要がある。
Decision:
すべての金額を整数の円単位で保存・計算する。
割り切れない端数は、メンバーリストの先頭から1円ずつ配分する。
Consequences:
新しいADRが作成されるまでは、USDのセントなどの小数単位には対応しない。
表示時のみ適切な形式に変換する。
このスキルは、受動的にドキュメントを作るだけではありません。
設計中に新しい用語が登場すると、既存のGLOSSARY.mdと照合します。同じ意味の用語がすでに存在する場合は、その違いを確認します。
また、新しい用語や設計判断が確定したタイミングで、すぐに記録します。
ここでも、Step 1のヒアリングスキルから取り入れた重要なルールがあります。
ADRには、人間が確定した意思決定だけを記録すること。AIにアーキテクチャ上の決定を勝手に書かせてはいけません。
AIエージェントが過去のADRに反する実装を提案した場合、チャット上で何度も議論する必要はありません。該当するADRを提示すればよいのです。
Step 3:技術計画を作成し、レビュアーの視点で確認する
ここで初めて、仕様書をAIに渡して技術計画を作成させます。
ただし、この段階ではまだコードを書かせません。
Claude Codeでは、Planモードを利用します。
エージェントはコードやドキュメントを読み、設計を提案しますが、ファイルの変更は行いません。
使用するプロンプトは次のとおりです。
spec.md、AGENTS.md、GLOSSARY.md、docs/adrを読んでください。
以下の内容を含むplan.mdを作成してください。
- データモデル
- Route/API
- 金額計算ロジックの配置場所
- 端数処理の方法
- リスク
- まだ不明確な点
まだコードは書かないでください。
仕様が不明確な箇所は、確認が必要な質問として列挙してください。
この段階で人間が行うべきことは、同僚が作成した設計ドキュメントをレビューするように、plan.mdを読むことです。
私がよく確認する質問は次のとおりです。
| 確認事項 | 割り勘アプリでの例 |
|---|---|
| 仕様で対象外とした機能が含まれていないか? | 仕様では複数通貨に対応しないのに、currenciesテーブルが提案されていないか |
| 最も難しい部分が明確に説明されているか? | 100,000円を3人で割る場合、余った1円を誰が受け取るのか |
| データ設計が実際の利用状況に合っているか? | メンバーが退会した場合、削除するのか、ステータスで管理するのか。削除すると過去の債務履歴が失われないか |
| 不必要なライブラリを追加していないか? | 画面が3つしかないアプリに、状態管理ライブラリが必要なのか |
コードを修正するよりも、planを修正する方がはるかに低コストです。
計画段階での1行の間違いが、Step 5では5つのファイルに影響する可能性があります。
さらに深掘り:依存関係と検証方法を含めたPlan、そして設計への反論
planスキルでは、planの各ステップに次の5つの情報を含めるようにしています。
- 実施する作業とその順序
- 変更対象のファイル
- 他の作業との依存関係
- 受け入れ基準
- 結果を検証するためのコマンド
さらに、--tddオプションを付けると、各ステップを失敗するテスト(Red)から開始するようにします。
割り勘アプリの計画の一部は、次のようになります。
### Step 2. 残高計算と精算
(依存関係:Step 1 splitEqually)
- Files:
src/domain/settle.ts
src/domain/settle.test.ts
- Acceptance Criteria:
- すべての送金を実行した後、全員の残高が0になること。
- 送金回数がグループの人数より少ないこと。
- Verification:
pnpm vitest run src/domain/settle.test.ts
(Step 5で説明するプロパティベーステストを含む)
その後、作成したplanをarchitecture-advisorスキルに渡し、設計の弱い部分を指摘させます。
このスキルは、コードを読み込んだうえで、必ず1回に1つずつ質問します。
また、同じ目的を達成するための2〜3種類の代替案を提示します。その中には「もっと簡単に実装する」「そもそも実装しない」という選択肢も含まれます。
最後に、何を実装すべきか、何を避けるべきかを明確に提示します。
今回の割り勘アプリであれば、次のような質問が特に重要です。
「すでに登録されている支出を編集した場合、残高を最初から再計算しますか? それとも差分だけを加減算しますか?」
最初のplanでは、この点が明確になっていませんでした。
しかし、実際にはここがバグの発生しやすいポイントになります。
Step 4:作業を小さなタスクに分割し、それぞれに検証方法を用意する
planをもとに、AIにtasks.mdを作成させます。
ここでのルールは1つだけです。
すべてのタスクに、完了したことを検証できる方法を用意すること。そして、数分で差分をレビューできる程度に小さくすること。
# tasks.md
- [ ] T1. src/domain/split.ts に均等分割関数を実装する
検証:サンプルテスト + 「合計が常に元の金額と一致する」
というプロパティテスト
- [ ] T2. 残高計算と精算処理を実装する
検証:「精算後、すべての残高が0になる」
というプロパティテスト
- [ ] T3. groups、members、expensesテーブルとmigrationを作成する
検証:空のデータベースでmigrationが成功し、rollbackできること
- [ ] T4. 支出追加フォーム(Server Action)とバリデーションを実装する
検証:負の金額、分配対象0人のテスト
および支出追加のE2Eテスト
- [ ] T5. 「誰が誰に支払うか」の画面を実装する
検証:サンプルデータを使用したE2Eテストで、
期待する一覧が表示されること
作業の順番にも注目してください。
まず、純粋なロジック(T1、T2)を実装し、その後にUIを作ります。
純粋なロジックはテストしやすく、間違えた場合の影響も大きい部分です。
割り勘アプリで計算が間違っていれば、どれだけ美しいUIを作っても意味がありません。
さらに深掘り:12の観点から境界条件を洗い出す
「境界条件をもっと考えてください」という指示はよく使われます。
しかし、どこまで考えれば十分なのかは明確ではありません。
edge-case-scenario-genスキルでは、機能を次の12の観点から確認します。
- ユーザーの種類
- 極端な入力値
- タイミングと競合
- 規模
- 状態遷移
- 実行環境
- 障害の連鎖
- 権限
- データ整合性
- 外部連携
- コンプライアンス
- ビジネスロジック
重要なのは、確認しない観点がある場合、その理由となる前提条件を明記することです。
残りの観点については、それぞれ3〜5個のシナリオを作成し、重大度を設定します。
例えば、「支出追加と精算」機能に対して実行した結果の一部は次のとおりです。
| 観点 | シナリオ | 重大度 |
|---|---|---|
| 極端な入力値 | 2円を3人で分割する、0円、非常に大きな金額 | Critical |
| ビジネスロジック | 支払った人が分配対象に含まれていない | High |
| ビジネスロジック | 一部精算後に、既存の支出金額が変更された | Critical |
| 状態遷移 | 未払い残高がある状態でメンバーがグループを退会する | High |
| タイミング | 2人が別々のスマートフォンから同時に支出を追加する | High |
| 権限 | 招待リンクを持っている人が、他人の支出を変更できてしまう | High |
| データ整合性 | 「保存」ボタンを2回押すと、支出が重複登録される | Medium |
| 実行環境 | 名前に濁点や絵文字が含まれる場合、画面幅が320pxの場合 | Low |
また、確認対象から除外した観点についても、前提条件を記録します。
「外部連携」を除外:
決済サービスとは連携しないと仮定する(仕様書の「対象外」に記載)。
→ 将来「銀行アプリで送金する」ボタンを追加する場合、
この前提が崩れるため、リスクとして記録する。
完全に無視してはいけない。
「コンプライアンス」を除外:
表示名以外の個人情報を保存しないと仮定する。
この「除外する観点には必ず前提条件を記録する」というルールは、特に価値があると感じています。
これにより、今は関係ないと思っていることも、後から見直せる情報として残せます。
CriticalやHighに分類された項目は、tasks.mdのテスト項目に追加します。
Step 5:タスクごとに開発サイクルを回す
ここがAIに最も多くのコードを書かせる工程です。
tasks.mdに記載された各タスクについて、次のサイクルを繰り返します。
新しいセッション
│
▼
AGENTS.md + 対象タスクを1つだけ読む
│
▼
先にテストを書く
│
▼
AIがコードを実装する
│
▼
実行して検証する
│
▼
Lint + Typecheck + Test が成功
│
▼
自分で差分をレビューする
│
▼
小さくCommitする
│
└──────── 次のタスクへ
例えばT1の場合、まず仕様書の受け入れ基準からテストを作成します。
// src/domain/split.test.ts
import { describe, expect, it } from "vitest";
import { splitEqually } from "./split";
describe("splitEqually", () => {
it("分配額の合計が常に元の金額と一致する", () => {
const parts = splitEqually(100_000, ["An", "Bình", "Chi"]);
expect(
parts.reduce((s, p) => s + p.amount, 0)
).toBe(100_000);
});
it("端数は先頭のメンバーに配分し、各メンバーの差は最大1円とする", () => {
expect(
splitEqually(2, ["An", "Bình", "Chi"]).map((p) => p.amount)
).toEqual([1, 1, 0]);
});
it("整数以外の金額を拒否する", () => {
expect(() => splitEqually(10.5, ["An"])).toThrow();
});
});
その後、AIにテストが成功するコードを実装させます。
// src/domain/split.ts
export function splitEqually(amount: number, members: string[]) {
if (!Number.isInteger(amount) || amount < 0) {
throw new Error("金額は0以上の整数である必要があります(単位:円)");
}
if (members.length === 0) {
throw new Error("少なくとも1人のメンバーが必要です");
}
const base = Math.floor(amount / members.length);
let remainder = amount - base * members.length;
// 余りは必ずメンバー数より小さい
return members.map((member) => ({
member,
amount: base + (remainder-- > 0 ? 1 : 0)
}));
}
この開発サイクルを維持するために、3つの習慣が重要です。
1. タスクごとに新しいセッションを開始する
Claude Codeのドキュメントでも、コンテキストがいっぱいになると品質が低下すると説明されています。
1つのセッションで5つのタスクを続けて実行すると、タスク1の詳細をタスク5の実装中に混同する可能性があります。
タスクが完了したらcommitし、次のタスクでは新しいセッションを開始します。
2. テストを先に書き、AIにテストを変更させない
AIエージェントがよく行う「不正」は、テストが失敗したときにテスト自体を変更して成功させようとすることです。
Step 2のAGENTS.mdに記載したルールは、この問題を防ぐためのものです。
もちろん、テストファイルの差分も必ず自分で確認する必要があります。
3. 小さくcommitする
1つのタスクにつき1つのcommitを作成し、すべての差分を確認できる状態にします。
小さなcommitは、問題が発生した場合に元へ戻すための最も簡単な手段でもあります。
AIが間違った方向に進んだ場合、1行ずつ修正するのではなく、直前のcommitに戻せばよいのです。
さらに深掘り:プロパティベーステストで、コードを壊す入力を機械的に探す
上記の3つのテストは、3つの具体的なケースを確認しています。
では、57円を2人で割った場合や、99,999,998円を17人で割った場合はどうでしょうか?
プロパティベーステスト(Property-Based Testing)は、すべての入力に対して成立すべき条件を定義し、ライブラリに大量のランダムな入力を生成させて、条件を破るケースを探す手法です。
property-based-testingスキルでは、よく使われるプロパティの一覧を用意しています。
例えば、次のようなものです。
- 不変条件(Invariant)
- 往復性(Round-trip)
- 冪等性(Idempotency)
- 参照実装との比較
また、重要な注意点もあります。
テスト対象の関数とまったく同じ計算方法でプロパティを検証してはいけません。
同じ間違いを両方に含めてしまうと、テストが成功してしまうからです。
割り勘アプリでは、fast-checkを使って次のようなプロパティを作成できます。
import fc from "fast-check";
const amount = fc.integer({ min: 0, max: 100_000_000 });
const members = fc.uniqueArray(
fc.string({ minLength: 1, maxLength: 6 }),
{ minLength: 1, maxLength: 20 }
);
it("分配額の合計は必ず元の金額と一致する", () => {
fc.assert(
fc.property(amount, members, (a, m) => {
expect(
splitEqually(a, m).reduce((s, p) => s + p.amount, 0)
).toBe(a);
})
);
});
it("任意の2人の分配額の差は最大1円である", () => {
fc.assert(
fc.property(amount, members, (a, m) => {
const parts = splitEqually(a, m).map((p) => p.amount);
expect(
Math.max(...parts) - Math.min(...parts)
).toBeLessThanOrEqual(1);
})
);
});
この手法の効果を確認するために、AIエージェントが特に指示されていない場合に実装しがちな、単純な丸め処理を使ってみます。
const naive = (amount: number, members: string[]) =>
members.map((member) => ({
member,
amount: Math.round(amount / members.length)
}));
実際に実行すると、次の結果になりました。
Error: Property failed after 1 tests
Counterexample: [57,[" ","!"]]
Shrunk 45 time(s)
Caused by: AssertionError:
expected 58 to be 57
結果を説明すると、fast-checkは最初のテストで問題を発見しました。
その後、45回の縮小処理(Shrinking)を行い、バグを再現できる最小に近い入力を見つけました。
57円を2人で割るケースです。
それぞれ29円に丸められるため、合計は58円になります。
つまり、元の金額より1円多くなってしまいます。
これは、記事の冒頭で紹介した「100,000円を3人で割ると99,999円になる」という問題と同じ種類のバグです。ただし、今回は逆方向の誤差が発生しています。
一方、先ほど実装した正しい関数は、2つのプロパティテストを通過しました。それぞれ100個のランダムな入力を使って検証しています。
T2の精算関数には、さらに強力なプロパティを適用できます。
2〜8人のグループと最大30件の支出をランダムに生成し、残高を計算した後、settle()が提案する送金を実行します。
そして、次の2つを検証します。
- すべてのメンバーの残高が0になること。
- 送金回数がメンバー数より少ないこと。
このプロパティは内部のアルゴリズムではなく、最終的な結果を検証するものです。
そのため、AIが内部のアルゴリズムを変更しても、テストの価値は維持されます。
さらに深掘り:セッション間の引き継ぎ
「タスクごとに新しいセッションを開始する」という方法には、1つ問題があります。
新しいセッションは、前のセッションで決定した内容を知りません。
1つのセッションで終わらない長いタスクの場合、終了前にsession-handoff-contractスキルを使い、plans/handoffs/に引き継ぎファイルを作成します。
このファイルには、次の9つの項目を含めます。
- 目的と現在の進捗状況
- 変更を許可されている範囲
- リポジトリの状態(ブランチ、commit、変更中のファイル)
- 確定した意思決定と、採用しなかった代替案
- 完了した作業
- 実行済みの検証と、まだ実行していない検証
- 未解決のリスク
- 次に実施する作業とその順序
- 参照元のドキュメントやファイルへのパス
次のセッションでは、過去の会話をすべて読み直すのではなく、この引き継ぎファイルを読みます。
これにより、前日に却下した設計案を、次の日にAIが再び提案してくることも防げます。
Step 6:自分が深夜3時に障害対応するつもりでコードをレビューする
Simon Willisonが提唱しているルールの中で、私が最も重要だと感じているものがあります。
これは、「Vibe Coding」と本格的なソフトウェア開発を分ける明確な基準でもあります。
他人に説明できないコードをcommitしてはいけない。
「なんとなく正しそう」では不十分です。
そのコードが何をしているのか、なぜその実装が必要なのかを説明できなければなりません。
AIが作成したコードの差分を確認するとき、私は次のチェックリストを使っています。
[ ] 差分は現在のタスクに必要な範囲だけに限定されているか?
ついでに別の箇所まで変更していないか?
[ ] planにないライブラリ、ファイル、抽象化を追加していないか?
[ ] テストコードが緩和されていないか?
assertの削除、skipの追加、期待値の変更など。
[ ] エラー処理が適切に実装されているか?
try/catchでエラーを握りつぶしていないか?
[ ] 関数名や変数名がGLOSSARY.mdと一致しているか?
[ ] 同僚に各処理の内容を説明できるか?
理解できないコードがあれば、AIエージェント自身に質問します。
例えば、
「なぜここでは事前に計算せず、remainder--を使っているのですか?」
と聞きます。
回答が回りくどく、明確な理由がない場合は、よりシンプルな実装に書き直した方がよいかもしれません。
さらに深掘り:デフォルトで疑うレビュアー
AIによるコードレビューは、簡単に「LGTM」になってしまうことがあります。
モデルには、コードを書いた人の意見に同調しやすい傾向があるからです。
code-quality-auditorスキルは、これとは逆のアプローチを取ります。
私が、手動レビューでも適用すべきだと考えている原則は次のとおりです。
- コードはAIが書いたものだと仮定する。 コードがきれいだから、コメントに自信があるから、正常系のテストが通るからといって、無条件に信用しない。
- すべての指摘にコード上の根拠を付ける。 ファイル名、行番号、問題を再現する入力を示す。「パフォーマンスに問題があるかもしれない」といった曖昧な指摘はしない。
- 要求された範囲を守る。 ユーザーが要求した機能を勝手に削除する提案はしない。一方、要求されていないコードが追加されている場合は、その内容とコストを明確に指摘する。
- 新しい検証結果がない限り、完了を宣言しない。 修正後はテストやビルドを再実行し、その結果を確認してから完了を報告する。
先ほどのnaive実装であれば、このスキルによる指摘は次のようになります。
File: src/domain/split.ts
問題:
各メンバーの金額を個別に丸めているため、
合計金額が元の金額と一致しない。
再現例:
[57円、2人] → 合計58円
根拠:
プロパティベーステストで検出された反例。
重大度:
Critical
違反している仕様:
spec.md の受け入れ基準 No.1
このように、ファイル、入力値、理由、重大度を明確に示します。
GitHubのPR差分については、github-pr-reviewerスキルも同様の考え方でレビューを行い、AI Slopにつながる実装パターンを指摘します。
Step 7:リリースし、発生した不具合を次の自動チェックに変える
本番環境へのリリースは、これまで使ってきた通常の開発プロセスに従います。
- CIが成功していること
- PRごとにプレビュー環境が用意されていること
- デプロイを実施すること
- ログとアラートを設定すること
AIを使うからといって、この部分を変更する必要はありません。
むしろ、それが重要です。
DORAが示しているように、優れたリリースプロセスは、AIを良い方向に活用するための基盤になります。
AIによって大きく変わるのは、リリース後の対応です。
人間が原因であっても、AIエージェントが原因であっても、不具合が発生したら、All Code Is Slopで紹介されている次の4つの質問を順番に確認します。
- 型システムで防げないか?
- lintルールで防げないか?
- テストで防げないか?
- それでも難しい場合は、
AGENTS.mdに記録するしかないか?
例えば、AIエージェントが金額の計算にparseFloatを使ってしまったとします。
このとき、AGENTS.mdに10個目の注意事項を追加する必要はありません。
代わりに、src/domain/でparseFloatの使用を禁止するlintルールを追加します。
そうすれば、次回からはAIも人間も同じミスを繰り返すことができなくなります。違反すればCIが失敗するからです。
さらに深掘り:リリースゲートとGit履歴から繰り返し発生する問題を探す
branch-shipper-prスキルでは、最終工程を決められた手順にまとめています。
- テストを実行する
- コードレビューを行う
- commitする
- pushする
- PRを作成する
- レビュー完了かつCI成功後にのみmergeする
このスキルの価値は、コマンド入力を数回減らすことではありません。
忙しいときでも、必要な工程を飛ばさないことにあります。
では、「どのような不具合が繰り返し発生しているのか?」という問題は、どうやって調べればよいでしょうか。
記憶だけで判断するべきではありません。
sprint-retro-generatorスキルは、指定期間のGit履歴を分析し、次のようなデータを抽出します。
- 最も多く変更された10個のファイル
- 変更量に対するChurn(追加したコードと削除したコードの割合)
- テストファイルと実装ファイルの変更比率
- commitの頻度
- これらのデータに基づく改善提案
変更回数が多く、Churnも高い一方で、テストが少ないファイルは、優先的に見直すべき候補です。
「この問題は型やlintルールで防げないか?」という問いを考えるうえで、非常に有用です。
こうして時間が経つにつれて、コードベースには自動チェックが蓄積され、AIがコードを書くためのルールもより厳密になっていきます。
これが、コードの量を増やしながら、品質を低下させないための方法です。
まとめ:7つのステップ
| Step | 人間が行うこと | AIが行うこと | 成果物 | PrimeKit Skill |
|---|---|---|---|---|
| 1. Spec | 回答し、対象外の機能を確定する | 1つずつ質問し、回答を記録する | spec.md |
interview-spec-extractor、clarify
|
| 2. 開発ルール | Stack、規約、意思決定を確定する | 設定を提案し、用語集を管理する |
AGENTS.md、GLOSSARY.md、ADR、CI |
domain-modeling |
| 3. Plan | レビューし、設計上の質問に回答する | 設計を提案し、弱点を指摘する | plan.md |
plan、architecture-advisor
|
| 4. Tasks | 境界条件の一覧を確認する | タスク分割、12の観点からの洗い出し |
tasks.md、edge-cases.md
|
edge-case-scenario-gen |
| 5. 開発サイクル | テストを確認し、差分をレビューする | テストを通すコードを書き、反例を探す | 小さなcommit、引き継ぎファイル |
property-based-testing、session-handoff-contract
|
| 6. Review | すべてのコードを説明できるようにする | 根拠を示して問題を指摘する | PR |
code-quality-auditor、github-pr-reviewer
|
| 7. リリース後 | 不具合を自動チェックに変える | リリースゲートを実行し、履歴を分析する | より強固な自動チェック |
branch-shipper-pr、sprint-retro-generator
|
Skillだけでは解決できないこと
多くのスキルを使ってみて、できることとできないことの境界が、より明確になりました。
今回紹介したスキルでも、次のことは解決できません。
- プロダクトで何を作り、何を作らないかを決めること。 ヒアリングスキルはユーザーの意図を記録するだけです。勝手に新しいアイデアを追加しないように設計されています。
- 何をテストすべきかを判断すること。 fast-checkは反例を探すのが得意ですが、「分配額の合計が元の金額と一致する」というプロパティ自体は、仕様から人間が考える必要があります。
- mergeされたコードに責任を持つこと。 AIレビューによって不具合の見落としを減らすことはできますが、自分自身がコードを説明できることの代わりにはなりません。
- いつ開発プロセスを簡略化すべきかを判断すること。 次のセクションで説明する内容は、人間による判断であり、スキルが自動的に決められるものではありません。
すべてのステップを実行する必要はない
今回紹介したフルプロセスは、長期間運用され、実際のユーザーが利用するプロダクトを対象としています。
すべての開発で、必ず7つのステップを実施する必要はありません。
小さく、明確なバグ修正の場合
Step 1、3、4を省略しても構いません。
ただし、テストとレビューは維持します。
Claude Codeのドキュメントでも、内容が明確な小規模タスクでは、Planを作成するコストが余分になる場合があると説明されています。
アイデアを試すためのPrototypeの場合
最終的に破棄する予定であれば、Vibe Codingを自由に使っても構いません。
Simon Willisonも、このような使い方を肯定しています。
ただし、重要なのは、Prototypeを本当に破棄することです。
Prototypeがいつの間にか本番環境のコードとして使われることがないように注意してください。
大規模で、すでに熟知しているコードベースの場合
これはMETRの研究対象と同じ状況です。
場合によっては、AIを使うよりも自分でコードを書いた方が速いこともあります。
実際の作業でAIを使った場合と使わなかった場合の時間を測定することが、自分にとってどちらが効率的なのかを知る唯一の方法です。
1ページで確認できるチェックリスト
開発を始める前や、各工程の完了時に確認できるよう、重要な項目をまとめました。
[ ] spec.mdに「対象外の機能」と測定可能な受け入れ基準がある
[ ] AGENTS.mdは簡潔に保たれている。
機械的に検証できるルールはlintやテストに移している
[ ] ドメイン用語を管理するGLOSSARY.mdがある。
確定した意思決定はADRに記録している
[ ] 最初の機能コードを書く前に、
lint、typecheck、test、CIを準備している
[ ] plan.mdに依存関係、受け入れ基準、検証コマンドがある。
実装前に内容をレビューして修正している
[ ] 境界条件を洗い出している。
確認対象から除外した観点には前提条件を記録している
[ ] 各タスクが小さく分割され、検証方法が定義されている。
純粋なロジックをUIより先に実装している
[ ] 重要なロジックには、サンプルテストだけでなく
プロパティベーステストも導入している
[ ] タスクごとに新しいセッションを開始している。
長い作業には引き継ぎファイルを作成している
[ ] AIにテストを書き換えさせて、無理やり成功させていない
[ ] 自分で説明できないコードをmergeしていない
[ ] リリース後に発生した不具合を、自動チェックに変換している
最後に
まずは、以前から考えていた小さなアイデアを1つ選び、AIエージェントを起動してみてください。
Step 1のプロンプトを貼り付け、15分ほどAIの質問に回答してみましょう。
まだコードを書く必要はありません。
それだけでも、作ろうとしているアイデアに、どれほど未検討の部分が残っているかが見えてくるはずです。
次に、現在のプロジェクトで最も重要な関数を1つ選び、その関数に対してプロパティベーステストを1つ書いてみてください。
皆さんは、AIを使った開発でどのようなワークフローを採用していますか?
また、開発工程の中で、最も省略されがちなステップは何でしょうか?
ぜひコメントで教えてください。
参考リンク