doand.tech

Claude Codeのスキャフォールド駆動開発｜計画一式を先に作る手法

  • スキャフォールド
  • プロジェクト立ち上げ
  • Claude Code

新しいプロジェクトを Claude Code で始めるとき、いきなりコードを書かせるのではなく、計画・契約・エージェント定義・コマンドの一式を先に生成しておく——本稿はこの「スキャフォールド駆動」を扱う。着工後に足したルールや計画は、作業の文脈に組み込まれにくい。だからこそ実装の前に足場を組む。筆者が十数のプロジェクトで反復してきた標準構成を、この記事を生んだ記事制作ワークストリームの24ファイルの実物とともに整理する。

なぜ計画一式を先に作るのか

理由は単純で、後から足した構造は参照されないからである。 作業がいったん走り出すと、モデルは着工時に読み込んだ文脈の上で判断を積み上げていく。途中で新しいルールファイルや計画メモを書いても、明示的に読ませない限り、それは既存の判断列に自動では組み込まれない。人間が「ルールに従って」と言っても、そのルールが最初のコンテキストに無ければ効きは弱い。

順序を逆にすると、この摩擦が消える。実装を頼む前に、守るべき契約・作るものの計画・止まるべきゲートを先に置いておけば、モデルの一つひとつの判断は最初からその足場を参照できる。仕様が固まる前に書かれて捨てられるコードも減る。スキャフォールドとは、コードそのものではなく、コードを正しく生ませるための構造物である。建物より先に足場を組むのと同じで、前提を先に固定しておくことが、長い作業を破綻させないための最初の一手だと考えている。

スキャフォールドの標準構成

反復して見えてきた標準構成は、役割の異なる4区画に分かれる。docs（計画・モデル配分）／ rules（契約）／ agents（担当）／ commands（実行手順） である。

  • docs — 何を作るか、どのモデルで進めるか、どのゲートで止まるかを書く。フェーズ計画がプロジェクト全体の背骨になり、進捗と承認履歴もここに残す。
  • rules — 守るべき契約。領域ごとに分け、ID を振って会話から呼べるようにする（CLAUDE.md 本体を薄く保つ設計は別稿で扱う）。
  • agents — 誰にやらせるか。生成・検証・探索といった役割ごとにサブエージェントを定義し、model を明示する。
  • commands — 各フェーズの実行手順。ゲートで停止する運用を、コマンド自体に埋め込む。

4区画は独立ではなく、依存の連鎖でつながっている。commands が docs のフェーズ計画（ゲート）を参照し、agents に作業を委譲し、rules を遵守させ、docs のなかの雛形を成果物で上書きしていく。 実際のツリーは次のとおりである（区画ごとに主要ファイルのみ、他は # … で省略）。

.claude/
├── rules/
│   ├── articles-code-example-contract.md   # コード例の契約
│   ├── articles-dedup-policy.md            # 外部との棲み分け
│   ├── articles-links-sources.md           # 内部リンク・参照
│   └── articles-numeric-contract.md        # 数値注入契約
│   # … サイト構築時の 00〜50 も同居
├── agents/
│   ├── article-writer.md                   # model: opus
│   ├── article-reviewer.md                 # model: opus
│   └── content-scanner.md                  # model: haiku
│   # … 実装系エージェントも同居
└── commands/
    ├── adapt-repo.md
    ├── build-site-req.md
    ├── inventory.md
    ├── plan-articles.md
    └── write-article.md
    # … サイト運用系コマンドも同居
docs/hub-articles/
├── articles-phase-plan.md                  # フェーズ計画・ゲート・進捗表
├── model-plan.md                           # モデル/effort 配分
├── article-outlines-claude.md              # 構成案（入力資産）
├── article-outlines-population.md
├── integration-plan.md
├── content-inventory.md                    # ← 成果物で上書きされる雛形
├── article-plan.md                         # ← 同上
│   # … 稼働後に増える検証ログ等は省略
└── templates/
    ├── article-template.md
    ├── about-author.md
    ├── contact.md
    ├── disclaimer-sources.md
    └── privacy-policy.md

解剖 — 実プロジェクトの24ファイル

この4区画を、実際に稼働している記事制作ワークストリームで数えると24ファイルになる。内訳は rules 4本・agents 3本・commands 5本・docs 7本・templates 5本 である。着工前に一括生成し、リポジトリに統合してから記事の執筆を始めた。

連携は実物で追える。記事1本を書く /write-article コマンドは、まず本文担当の article-writer（model: opus）を spawn し、構成案・素材・リンク解決表とともに rules を渡す。次にコード例を抜粋元と照合し、レビュー専用の article-reviewer を別コンテキストで走らせる。そして記事ゲートの条件をチェックリストで提示し、人間の承認を待って停止する。承認されると、docs/hub-articles/articles-phase-plan.md の進捗表に承認日が追記される。探索だけを担う content-scanner は model: haiku に固定され、上位モデルを浪費しない（役割別のモデル指定は別記事で扱う）。

雛形が成果物に化けていく点も、この構成の要である。docs/hub-articles/ に置かれた content-inventory.md と article-plan.md は、当初は空の雛形だった。素材インベントリのフェーズがスキャナの列挙で前者を埋め、計画フェーズが素材の突き合わせで後者を確定させた。雛形は消費されるのではなく、上書きされて次のフェーズの入力になる。そして——いま読んでいるこの記事自体が、その /write-article で生成されている。 スキャフォールドは、それを説明する記事すらも生む足場になっている。

生成プロンプトの設計

スキャフォールドを生成させるプロンプトで指示すべきは、守らせる制約と止め方である。具体的には、根拠となるルール ID を出力に添えさせること、フェーズのゲートを明示すること、モデルと effort の配分を決めること、そして「まだコードは書かない」フェーズを最初に置くことである。逆に、実装の細部は委ねる。曖昧な点はモデルに「最も妥当な仮定」を明示させて進めさせ、確定は人間のゲートで行う。

同じ手法を、このリポジトリでは2周させている。1周目はハブサイト本体の構築、2周目が今回の記事制作ワークストリームである。1周目の投入プロンプト実物（docs/PROMPTS.md）には、モデル配分と「コードを書かない」指示がそのまま残っている。

主作業は Opus、実装サブエージェントは Sonnet を割り当てると費用対効果が良い
（`export CLAUDE_CODE_SUBAGENT_MODEL="claude-sonnet-4-6"`、調整役だけ `claude --model claude-opus-4-8`）。
# …
各項目に根拠のルールID（ARCH-/DATA-/CODE-/DSGN-/SEO-/DEPLOY-）を添える。
まだコードは書かない。曖昧な点は「最も妥当な仮定」を明示して進める。

引用中のモデル名 claude-sonnet-4-6 / claude-opus-4-8 は、このサイトを構築した当時（2026年前半）の実物であり、原文のまま載せている。モデル名は揮発情報なので、投入時点のバージョンを付記しておくのがよい（本稿の検証環境は Claude Code v2.1.211、2026-07-16 確認）。枠を先に固め、中身は委ねる——これが生成プロンプトの勘所である。

よくある質問

小規模なプロジェクトでも一式を作るのか。 規模に応じて縮める。使い捨てのスクリプトに4区画は過剰で、CLAUDE.md 一枚で足りることも多い。足場のコストが手戻りのコストを上回るなら省けばよい。判断の基準は行数ではなく、工程の長さと手戻りの痛みである。

既存リポジトリに後付けできるのか。 できる。着工済みのリポジトリには、現物を読んで足場を当てる適応フェーズを挟む。本ワークストリームの /adapt-repo コマンドがまさにその後付け統合の実例で、既存のハブサイトに記事制作の足場を重ねる設計をゲート付きで行っている。

まとめ

Claude Code のスキャフォールド駆動は、実装より先に docs・rules・agents・commands の4区画を一式で生成し、実装の各判断が最初から契約とゲートを参照できる状態を作る手法である。後から足した構造は文脈に組み込まれにくい——だからこそ順序を先にする。この手法で立ち上げたツールには人口カルテ47や国会議事録 AI要約があり、そして本稿もまた、その足場が生んだ成果物である。フェーズとゲートの運用そのものは別記事で詳しく扱っている。

--- 参照: 同じ手法を1プロジェクトの事例として時系列で述べた記事に「DBレス統計可視化サイトの設計判断」（Zenn, https://zenn.dev/saneyuki_rokaru/articles/estat-population-web-claude-code-design 、2026-07-16 確認）がある。本稿は手法を体系として整理したもので、同記事の内容を転載していない。