はじめに
本記事は「GitHub Copilot + MUSUBIX3 によるAI Coding」シリーズのVol.1（初学者編）です。
本シリーズは全4巻構成で、レベルが上がるほど開発するシステムを複雑化させながら、実際に手を動かして GitHub Copilot CLI + musubix3 を使ったAI Codingを実演します。
| 巻 | 対象 | テーマ |
|---|---|---|
| Vol.1（本記事） | 初学者 | シンプルなTODO管理CLIアプリ |
| 第2巻 | 中級者 | DB連携ありのREST API |
| 第3巻 | 上級者 | マイクロサービス構成システム |
| 第4巻 | プロ | エンタープライズ級・組織運用 |
各巻で使うコマンドや考え方（要求→設計→実装→トレーサビリティ→品質ゲート）は共通です。Vol.1でこの流れを体に馴染ませておけば、第2巻・第3巻と題材が複雑になっても「やることは同じ」で読み進められ、第4巻に到達する頃には、複数チーム・長期保守を前提とする開発で必要になる、仕様・証跡を残すSDDの基礎的な型を段階的に身につけられる構成になっています。本記事はその第一歩、最短ルートです。
この記事を読み終えると、次のことができるようになります:
- WSL + GitHub Copilot CLI +
musubix3の開発環境を自分のPCに作れる - 「要求を書く→設計する→実装する→トレースを繋ぐ→品質ゲートを通す」という一連の流れを、実際にTODO管理CLIを題材に手を動かして体験できる
- なぜ「AIに雑に投げて動いたらOK」（Vibe Coding）ではなく、仕様駆動でAIコーディングをするべきなのか、自分の言葉で説明できる
なぜ「仕様駆動 × AI Coding」なのか
GitHub Copilotのように強力なAIコーディング支援があると、明確な要求や設計を固めずに、AIとの対話の"ノリ"（vibe）だけでコードを生成・修正し続ける——いわゆる 「Vibe Coding」 にしてしまいがちです。プロトタイプを素早く動かすには強力なスタイルですが、そのまま本格的な開発・チーム運用・保守フェーズに入ると、次の問題が顕在化します。
- 何を作るべきだったのか（要求）が記録に残らない
- なぜその設計にしたのか（設計判断）が失われる
- コードとテストが要求を満たしているか（トレーサビリティ）を検証できない
Vibe Codingの本質的な弱点は、「AIが生成したものが本当に正しいか」を判断する基準が、プロンプトを書いた本人の"vibe"（感覚）にしか存在しないことです。個人のToyプロジェクトなら許容できても、要求が変わった時に「どこに影響が及ぶか」「テストが本当に要求をカバーしているか」を誰も答えられなくなります。
musubix3 は、要求定義→設計→実装→トレーサビリティ→品質ゲートという一連のSDD（仕様駆動開発）プロセスをGitHub Copilot CLI上で回すためのツールです。両者の違いを整理すると次の通りです。
| 観点 | Vibe Coding | 仕様駆動×AI Coding（本シリーズ） |
|---|---|---|
| 出発点 | 「とりあえずこう動いて」という曖昧な指示 | EARS形式で検証可能な要求（REQ-*） |
| 変更の理由 | チャット履歴に埋もれて追跡困難 | ADR・設計書（DES-*）として明文化 |
| 「できた」の判定 | 見た目が動けばOK（属人的・主観的） |
requirements validate / design validate / trace check / gate による客観的合否判定 |
| 要求とコードの対応 | 誰も保証していない（AIの自己申告のみ） |
@implements / @verifies 注釈による機械検証可能なトレーサビリティ |
| 人間の関与 | 生成結果をなんとなく承認 |
approval record による、ハッシュ値に紐づいた明示的な人間承認 |
| 再現性・監査 | 同じ結果が二度と出せないことが多い | 要求・設計・コード・テスト・承認履歴がGit管理下で再現可能 |
| スケール耐性 | 個人の小規模開発では成立するが、チーム・大規模で破綻しやすい | 巻が進むほど複雑なシステムでも同じプロセスで運用可能（本シリーズの縦軸） |
musubix3 を使った仕様駆動×AI Codingは、AIコーディングの速度は活かしつつ、「なぜこのコードなのか」「要求・設計・テストがどう対応しているか」をツールで機械的に検証可能な形に残します。ただし誤解のないよう補足すると、これは「コードが意味論的に正しいこと」を自動証明するものではなく、要求・設計・実装・テスト・承認の対応関係の欠落や矛盾を検出しやすくするものです。これは本記事のStep 1〜5で実際に体験した通り、承認忘れ・ADR理由の未記載・トレース注釈漏れなどを容赦なくエラーにする、という形で具体化されています。Vibe Coding自体もプロトタイプ段階では有効な手法であり、継続的な保守・チーム協働のフェーズに入るタイミングで、仕様と証跡を残すプロセスへ移行する、という位置づけです。
同じような仕組みを持つツールに GitHub Spec Kit や AWS Kiro があります。他ツールとの違いや、なぜエンタープライズアプリケーション開発でmusubix3を選ぶのかは、記事末尾の「もっと知りたい人向け」コラムで扱っています。まずはVol.1の本編（環境構築〜TODO CLI実装）を先に進めましょう。
環境構築
本シリーズはWSL（Windows Subsystem for Linux）上での作業を前提とします。
やることは以下の7つです（1〜3の詳細手順は、それぞれの折りたたみを展開して確認してください。4〜7はそのまま順に実行します）:
| # | 内容 | 完了の目安 |
|---|---|---|
| 1 | WSL2 + Ubuntuを有効化 |
wsl -l -v でVERSIONが2
|
| 2 | Windows TerminalでUbuntuを開く | タブでUbuntuシェルが開ける |
| 3 | VS Code + WSL拡張機能をインストール |
code . で「WSL: Ubuntu」表示 |
| 4 | Node.js 22+をインストール |
node -v が v22.x.x
|
| 5 | 作業ディレクトリを作成 |
~/projects/todo-cli が存在 |
| 6 | GitHub Copilot契約 + Copilot CLIをインストール |
copilot --version が表示される |
| 7 | musubix3を導入 |
npx musubix3 init が完了 |
既にWSL/VS Code/Node.jsのセットアップ経験がある方は、1〜3は読み飛ばして4から始めて構いません。
1〜3. WSL2 / Windows Terminal / VS Code のセットアップ詳細（初めての方はこちらを展開）
1. WSLのセットアップ
WSL2はHyper-V（およびWindowsのVirtual Machine Platform）を利用して動作するため、事前にこれらの機能を有効化しておく必要があります。
1-1. WSL2 + Ubuntuのインストール（標準ルート）
Windows 10（バージョン2004、ビルド19041）以降、またはWindows 11であれば、次のコマンド1つで、必要な機能の有効化からUbuntuのインストールまで自動的に行われます。Windows PowerShell（管理者権限）で実行してください。
wsl --install -d Ubuntu
このコマンドは内部で「Linux用Windowsサブシステム」と「Virtual Machine Platform」を自動的に有効化します。インストール後、再起動を求められたら再起動し、初回起動時にUbuntu用のユーザー名・パスワードを設定します。
正しくセットアップできているかは、PowerShellから次のコマンドで確認できます。
wsl --status
wsl -l -v
wsl -l -v で対象ディストリビューションの VERSION が 2 になっていればOKです。
1-2. Hyper-Vの有効化（手動で行いたい場合／自動有効化がうまくいかない場合）
上記の wsl --install で自動的にセットアップされない環境や、Hyper-Vを使う他のツール（Dockerの一部構成など）も併用する場合は、Hyper-Vを含む仮想化機能を手動で有効化しておきます。PowerShell（管理者権限）で以下を実行します。
dism.exe /online /enable-feature /featurename:Microsoft-Hyper-V /all /norestart
dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
または「Windowsの機能の有効化または無効化」画面（optionalfeatures.exe）から、以下にチェックを入れてもOKです。
- Hyper-V
- Virtual Machine Platform
- Linux用Windowsサブシステム
加えて、PCのBIOS/UEFI設定で CPUの仮想化支援機能（Intel VT-x / AMD-V） が有効になっている必要があります（多くのPCは初期状態で有効ですが、無効な場合はBIOS/UEFI画面から有効化してください）。
Note: WSL2自体が必要とするのは「Linux用Windowsサブシステム」と「Virtual Machine Platform」であり、フルの「Hyper-V」ロールは必須ではありません。Windows Home エディションなど、Hyper-Vが単体で提供されない環境でも、この2つの有効化だけでWSL2は動作します。Hyper-Vは、Docker Desktopの一部構成など他ツールとの併用で必要になる場合に有効化してください。
設定変更後は一度Windowsを再起動してください。
2. Windows Terminalのセットアップ
Ubuntu（WSL）を操作するターミナルには Windows Terminal を利用します。
- Microsoft Storeで「Windows Terminal」を検索してインストール（Windows 11では標準搭載済みの場合もあります）
- Windows Terminalを起動し、タブ切り替えのプルダウン（▽ アイコン）から「Ubuntu」を選択して開く
- 以後、既定タブをUbuntuにしておくと便利です。Windows Terminalの設定画面（Ctrl+,）→「起動」→「既定のプロファイル」を「Ubuntu」に変更します
以降、本記事のコマンドはすべて Windows Terminal上で開いたUbuntu（WSL）のシェル で実行するものとします。
3. VS Codeのセットアップ
3-1. VS Code本体のインストール（Windows側）
- ブラウザで https://code.visualstudio.com/ にアクセス
- 「Download for Windows」ボタンをクリックし、インストーラー（
VSCodeUserSetup-x64-x.xx.x.exeなど）をダウンロード - ダウンロードしたインストーラーを実行
- ライセンス条項に同意し「次へ」を押していく
- 「追加タスクの選択」画面では、以下にチェックを入れておくと便利です
- デスクトップ上にアイコンを作成する
- PATHへの追加（インストール後に再起動しても反映されます）
- エクスプローラーのファイルコンテキストメニューに「Codeで開く」を追加する
- 「インストール」を押し、完了後「VS Codeを実行する」にチェックを入れたまま「完了」を押す
初回起動後、VS Codeの左サイドバー（アイコンの並び）が表示されればインストール成功です。
3-2. WSL拡張機能のインストール
- VS Code左サイドバーの「拡張機能」アイコン（四角が4つ並んだアイコン）をクリック
- 検索欄に
WSLと入力 - 発行元が Microsoft の「WSL」拡張機能を選択し、「インストール」ボタンをクリック
3-3. WSL（Ubuntu）フォルダをVS Codeで開く
- Windows Terminalで開いたUbuntuのシェル上で、作業用ディレクトリに移動する
- 次のコマンドを実行する
code .
初回実行時はVS Code側でWSL用のサーバーコンポーネントが自動でインストールされ、少し時間がかかります。完了すると、VS Codeのウィンドウが開き、左下に緑色で「WSL: Ubuntu」と表示されます。この表示があれば、VS CodeがWindows側ではなくWSL（Ubuntu）側のファイルシステムに接続できている状態です。
4. Node.jsのインストール（WSL/Ubuntu内）
GitHub Copilot CLIはNode.js 22以上が必要です。WSLのUbuntuターミナルで、nvm（Node Version Manager）を使ってインストールします。
# nvmのインストール
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
# シェルに反映（一度ターミナルを開き直してもOK）
source ~/.bashrc
# Node.js 最新LTSをインストール
nvm install --lts
# バージョン確認
node -v
npm -v
GitHub Copilot CLIはnpm経由で導入するため、比較的新しいNode.jsが必要です（本シリーズの検証環境ではNode.js LTS、node -v で v22.x.x を使用しています。正確な対応バージョンは npm view @github/copilot や公式インストールページで確認してください）。
5. プロジェクトディレクトリの作成
本シリーズを通して使う作業ディレクトリを1つ作成し、以後の手順（Copilot CLIのログイン、musubix3の導入、TODO CLIの実装）はすべてこの1つのディレクトリの中で行います。
mkdir -p ~/projects/todo-cli && cd ~/projects/todo-cli
git init
npm init -y
6. GitHub Copilot CLIのインストール
前提として、GitHub Copilotのサブスクリプション（Individual/Business/Enterprise等いずれか）が有効になっているGitHubアカウントが必要です。
npm install -g @github/copilot
インストール後、バージョンを確認します。
copilot --version
初回起動とログイン
先ほど作成した作業ディレクトリ（~/projects/todo-cli）で copilot コマンドを起動します。
copilot
初回起動時は次の手順でGitHubアカウントと連携します。
- 起動したCopilot CLI上で
/loginと入力 - 表示されるURLとワンタイムコードをブラウザで開き、GitHubアカウントでログイン・認可
- CLIに戻り、認証完了メッセージを確認
- 「このフォルダを信頼しますか？」といった確認が出た場合は、作業対象のフォルダであることを確認して許可する
これでCopilot CLI側の準備は完了です。次に、SDDプロセスを回すための musubix3 を、同じディレクトリに導入します。
7. musubix3の導入
musubix3 はグローバルインストールではなく、プロジェクトのdevDependenciesとしてバージョン固定で導入するのが安全です（npx musubix3 だけだとキャッシュ済みの古いバージョンが実行される場合があるため）。本記事は musubix3@0.1.16 で動作確認しています。
npm install --save-dev --save-exact musubix3@0.1.16
バージョンを確認し、まず --dry-run で何が生成されるかを確認してから実行します。
$ npx --no-install musubix3 --version
0.1.16
$ npx --no-install musubix3 init --dry-run
create .github/skills/sdd-change/SKILL.md
create .github/skills/sdd-requirements/SKILL.md
create .github/skills/sdd-design/SKILL.md
create .github/skills/sdd-implementation/SKILL.md
create .github/skills/sdd-traceability/SKILL.md
create .github/skills/sdd-quality/SKILL.md
create .github/skills/sdd-knowledge/SKILL.md
create .github/skills/sdd-formal-codegraph/SKILL.md
create .github/skills/sdd-issue-report/SKILL.md
create .musubix/config.json
create .musubix/policy-baseline.json
create .musubix/constitution.md
create .musubix/features/example/requirements.md
create .musubix/features/example/design.md
create .musubix/decisions/ADR-0001.md
create .musubix/evidence/quality.json
create .gitignore
create .musubix/features/example/trace.json
--dry-run はファイルを一切書き込みません。内容に問題なければ、同じ引数から --dry-run を外して実行します。
$ npx --no-install musubix3 init
create .github/skills/sdd-change/SKILL.md
...(dry-runと同じ一覧)
npx --no-install を付けることで、「今インストールされているローカルの musubix3 を確実に実行する」ことを保証しています（--no-install なしだと、ローカルに無い場合にnpmが黙って別バージョンを取得しに行くことがあります）。
.github/skills/ にはGitHub Copilot CLIが読み込むSDD用のSkillが、.musubix/ には要求・設計・品質基準（憲章）などの成果物が配置されます。
Step 1: EARS形式で要求を書く
musubix3 はEARS（Easy Approach to Requirements Syntax）形式の要求記述を検証できます。今回作るのはシンプルなTODO管理CLIです。
自然言語プロンプト→裏側で実行されるコマンド
GitHub Copilot CLI上で次のように自然言語で依頼すると、Copilotは .github/skills/sdd-requirements/SKILL.md の手順に従い、裏側で以下のコマンドを実行します（--jsonはCopilotが機械的に結果を読み取るために付けるオプションで、人間が実行する際は省略してもOKです）。
> TODO CLIの要件定義書作成を開始してください。タスクの追加・一覧表示・完了・永続化を扱います。
| # | 裏側で実行されるコマンド／動作 | 目的 |
|---|---|---|
| 1 | （CLI実行ではなくCopilotの対話）.musubix/features/todo-cli/requirements.mdを新規作成し、1問1答でヒアリングしながらEARS要求（Priority/Type/Pattern/Statement/Acceptance）を埋めていく |
要求内容の確定（sdd-requirements SKILL.md 手順1〜4） |
| 2 | npx musubix3 requirements validate .musubix/features/todo-cli/requirements.md --json |
EARS構文の検証 |
| 3 | npx musubix3 constitution validate --json |
憲章（品質基準）との整合確認 |
| 4 | Copilotのネイティブrubber-duckレビュー（CLIコマンドなし） |
要求内容の意味的な抜け漏れチェック。指摘ゼロになるまで2→4を繰り返す |
| 5 | npx musubix3 approval prepare requirements |
承認対象のファイル一覧とSHA256ハッシュを提示し、人間に承認を求める |
| 6 | （人間が承認した場合のみ）npx musubix3 approval record requirements --approver <name> --artifact-sha256 <hash> --confirm
|
承認をハッシュに紐づけて記録 |
| 7 | npx musubix3 workflow-record sdd-requirements complete --status completed |
このSkillの完了を証跡として一度だけ記録 |
Note:
.github/skills/sdd-requirements/SKILL.md自体は、自然言語の開発依頼を受けたら1問1答のヒアリングを経てrequirements.mdを編集する手順を指示しており、requirements scaffoldコマンドの利用は明示していません。後述するscaffoldコマンドは、ヒアリングを介さずファイルの型だけを機械的に用意したい場合に使う、Skillとは別の補助的な選択肢です。
以下は、このプロンプトが裏側で実際にどう動くか（要求記述そのものの中身と、日本語で依頼した場合の挙動）を、実際の実行結果で確認していきます。
「○○の要件定義書作成を開始」と伝えると、要件定義書の作成が始まる
musubix3 init で導入される .github/skills/sdd-requirements/SKILL.md には、次のように明記されています。
Respond and generate guidance in the user's input language (日本語 / English).
つまり、GitHub Copilot CLI上で「TODO CLIの要件定義書作成を開始してください」のように日本語で依頼すると、Copilotはこのskillに従って.musubix/features/<slug>/requirements.mdを新規作成し、要求を1問1答形式でヒアリングしながら埋めていきます。このとき、ヒアリングも生成される要件定義書の本文も日本語になります（英語で依頼すれば英語になります）。
実際に、別のクリーンな環境で「タスク削除機能の要件定義書作成を開始」という想定で、Statement・Acceptanceを含め全文日本語のEARS要求を作成し、検証してみました。
## REQ-DELETE-001: タスク削除
Priority: must
Type: functional
Pattern: event-driven
Statement: ユーザーがIDを指定してタスク削除を要求したとき、システムは該当タスクをタスク一覧から削除しなければならない。
Acceptance: `node todo.js delete <id>` を実行すると、該当IDのタスクが一覧から消え、他のタスクは変化しない。
## REQ-DELETE-002: 存在しないIDの扱い
Priority: must
Type: functional
Pattern: unwanted-behavior
Statement: もし指定されたIDのタスクが存在しないならば、システムはエラーメッセージを表示し、タスク一覧を変更してはならない。
Acceptance: `node todo.js delete 999`（存在しないID）を実行すると、"task not found" のようなエラーが表示され、一覧は変化しない。
$ npx musubix3 requirements validate .musubix/features/task-delete/requirements.md
PASS / 合格
このように、全文日本語のEARS要求でも問題なくPASSします。重要なのは、Priority: / Type: / Pattern: / Statement: / Acceptance: といったキー自体は英語で固定されているという点で、値（自然文の説明）は日本語・英語どちらでも構いません。
以降、本記事では英語Statement＋日本語見出しの併記スタイルで進めますが、日本語だけで統一したいチームは上記のように全文日本語で運用しても問題ありません。
musubix3（v0.1.16）には、機能ディレクトリとrequirements.md/design.mdのひな形を自動生成する requirements scaffold <slug> / design scaffold <slug> コマンドが用意されています。
日本語のプロンプトでひな形作成を発火する
GitHub Copilot CLI上で、次のように日本語の自然文で依頼してみます。
> TODO CLIのrequirements.mdのひな形を、musubix3のscaffoldコマンドで作成してください
この依頼を受けたCopilotは、.musubix/features/todo-cli/ がまだ存在しないことを確認したうえで、次のコマンドを実行します（実際にこのシリーズのデモ環境で発火・検証した結果です）。
$ npx musubix3 requirements scaffold todo-cli
Created .musubix/features/todo-cli/requirements.md
.musubix/features/todo-cli/ ディレクトリごと自動生成され、次のようなプレースホルダ入りのrequirements.mdが作られます。
---
schemaVersion: 1
feature: todo-cli
---
# Requirements / 要求
## REQ-TODO-CLI-001: Describe the requirement
Priority: must
Type: functional
Pattern: ubiquitous
Statement: The system shall TODO: describe the required behavior.
Acceptance: TODO: describe how this requirement will be verified.
--title "<text>" オプションでプレースホルダの見出しを指定することもできます（design scaffold には --title はなく、スラッグから見出しが自動生成されます）。また、既存ファイルを誤って上書きしないよう、同じ依頼をもう一度実行しても次のように失敗し、既存の内容は保護されます。
> もう一度、TODO CLIのrequirements.mdのひな形を作成してください
$ npx musubix3 requirements scaffold todo-cli
musubix3: Refusing to overwrite existing file: .musubix/features/todo-cli/requirements.md
Note: プレースホルダの
Statement/Acceptanceは"TODO:"という文字列を含んだままでもrequirements validateは構文としてPASSします（EARSのキー構造は満たしているため）。つまり検証PASSは「書き方が正しい」ことの証明であって、「内容が適切」であることの証明ではありません。プレースホルダのまま次工程に進まないよう、必ず内容を実際の要求に書き換えてください。
（なお、前節の「TODO CLIの要件定義書作成を開始してください」のような依頼でも、Copilotのファイル作成ツールが同様にディレクトリを自動生成します。scaffoldコマンドは、.github/skills/sdd-requirements/SKILL.mdのヒアリング工程を経ずに、まず型だけを機械的に用意したい場合の選択肢です。）
生成されたrequirements.mdのプレースホルダを、実際のTODO管理CLIの要求に書き換えます。CLIは node todo.js ... という形で呼び出す想定なので、Acceptanceもそれに合わせて書きます。
## REQ-TODO-001: Add task / タスク追加
Priority: must
Type: functional
Pattern: ubiquitous
Statement: The system shall allow a user to add a new task with a title.
Acceptance: Running `node todo.js add "buy milk"` creates a task with status "open".
## REQ-TODO-002: List tasks / タスク一覧表示
Priority: must
Type: functional
Pattern: ubiquitous
Statement: The system shall list all tasks with their status.
Acceptance: Running `node todo.js list` prints all tasks with id, title, and status.
## REQ-TODO-003: Complete task / タスク完了
Priority: must
Type: functional
Pattern: event-driven
Statement: When a user completes a task by id, the system shall mark it as "done".
Acceptance: Running `node todo.js done <id>` changes the task status to "done".
## REQ-TODO-004: Persist tasks / タスクの永続化
Priority: must
Type: functional
Pattern: ubiquitous
Statement: The system shall persist tasks to a local JSON file between runs.
Acceptance: Tasks added in one invocation are visible in a subsequent invocation.
検証コマンドを実行します。
$ npx musubix3 requirements validate .musubix/features/todo-cli/requirements.md
PASS / 合格
Step 2: 設計を書く
自然言語プロンプト→裏側で実行されるコマンド
要求が承認された後、次のように依頼すると、Copilotは .github/skills/sdd-design/SKILL.md に従って以下を実行します。
> 要件が承認されたので、TODO CLIの設計を進めてください。
| # | 裏側で実行されるコマンド／動作 | 目的 |
|---|---|---|
| 1 | npx musubix3 approval validate |
requirements承認が現在も有効か確認（stale/未承認なら設計に進まず停止） |
| 2 | （Copilotの対話）.musubix/features/todo-cli/design.mdを編集し、Responsibilities/Interfaces/Constraints/Requirements/ADRsを記述 |
設計内容の確定（sdd-design SKILL.md 手順1〜3） |
| 3 | npx musubix3 design validate .musubix/features/todo-cli/design.md --json |
設計スキーマ（Responsibilities/Interfaces/Constraints/Requirements/ADRs等）の検証 |
| 4 | npx musubix3 design c4 .musubix/features/todo-cli/design.md |
C4風の構成図（Mermaid）を生成 |
| 5 |
npx musubix3 trace build → npx musubix3 trace check
|
要求↔設計のリンク切れがないか事前確認 |
| 6 | Copilotのネイティブrubber-duckレビュー |
設計・ADRの意味的な抜け漏れチェック。指摘ゼロまで2→6を繰り返す |
| 7 |
npx musubix3 approval prepare design →（承認後）npx musubix3 approval record design --approver <name> --artifact-sha256 <hash> --confirm
|
設計承認の提示・記録 |
| 8 | npx musubix3 workflow-record sdd-design complete --status completed |
このSkillの完了を証跡として一度だけ記録 |
要求を満たす設計コンポーネントを定義します。ここでもし要求と紐づかない設計を書くと後段のトレーサビリティチェックで弾かれます。（前節と同様、npx musubix3 design scaffold todo-cli でdesign.mdのプレースホルダを機械的に用意することもできますが、Skill本来の手順はヒアリング結果を直接編集する形です。ここでは実際の設計内容をそのまま記載します。）
## DES-TODO-001: TaskStore component / タスクストア
Responsibilities: Load, save, and mutate the task list in a local JSON file.
Interfaces: loadTasks(), saveTasks(tasks), addTask(title), completeTask(id)
Constraints: Must not lose existing tasks on write; file path is `tasks.json` in cwd.
Requirements: REQ-TODO-001, REQ-TODO-003, REQ-TODO-004
ADRs: none
## DES-TODO-002: CLI component / CLIインターフェース
Responsibilities: Parse command-line arguments (add/list/done) and invoke TaskStore.
Interfaces: main(argv)
Constraints: Unknown subcommands print usage and exit non-zero.
Requirements: REQ-TODO-001, REQ-TODO-002, REQ-TODO-003
Depends-On: DES-TODO-001
ADRs: none
いきなり検証すると、こんなエラーに遭遇しました。
$ npx musubix3 design validate .musubix/features/todo-cli/design.md
musubix3: requirements approval is missing; record explicit current approval
before continuing. Run `musubix3 approval validate` for a full per-stage status.
「設計に進む前に、要求に対する人間の明示的な承認が必要」 というmusubix3の思想がここに現れています。AIが要求を作ったからといって、それを自動承認してはいけない、という設計です。
$ npx musubix3 approval prepare requirements
requirements artifact manifest: <prepareの出力に表示される完全なSHA-256>
.musubix/constitution.md
.musubix/features/todo-cli/requirements.md
$ npx musubix3 approval record requirements \
--approver nahisaho \
--artifact-sha256 <↑でコピーした完全なSHA-256> \
--confirm
Recorded explicit requirements approval by nahisaho for <同じSHA-256>.
※ artifact-sha256 は各自の成果物内容から計算される値なので、必ず自分の approval prepare の出力からコピーしてください（本記事の値をそのまま貼り付けても失敗します）。
承認後、design validateを実行すると、まず設計書に ADRs: none（理由なし）とだけ書いた状態でエラーになりました。
error DES_ADR_EXEMPTION_REASON: DES-TODO-001 declares "none" but must give a
concrete reason (e.g. "none — <reason>").
「ADRなし」と書く場合も、なぜADR不要なのか理由を明記させるという細かいガードがあります。ADRs: none — no architectural trade-off requiring a decision record; standard file I/O pattern のように理由を追記して再実行すると：
$ npx musubix3 design validate .musubix/features/todo-cli/design.md
PASS / 合格
Step 3: Copilotでコードを実装する
自然言語プロンプト→裏側で実行されるコマンド
設計が承認された後、次のように依頼すると、Copilotは .github/skills/sdd-implementation/SKILL.md に従って以下を実行します。
> 設計が承認されたので、この設計に基づいてtodo.jsを実装してください。
| # | 裏側で実行されるコマンド／動作 | 目的 |
|---|---|---|
| 1 | npx musubix3 approval validate |
requirementsとdesignの両承認が現在も有効か確認（不足・staleなら停止し、sdd-requirements/sdd-designに差し戻し） |
| 2 | 振る舞いの変更・バグ修正には、失敗するテストを先に用意し npx musubix3 tdd red <TEST-ID> --requirement <REQ-ID> --command <name> を記録 |
Red（失敗確認）の証跡化。sdd-implementation SKILL.mdが要求する本来の手順 |
| 3 | 変更なしのテストのままコードを実装し npx musubix3 tdd green
|
Green（成功）の証跡化 |
| 4 | （Copilotの対話）todo.jsとtodo.test.jsに@id/@implements/@design/@verifiesのブロックコメントを付与 |
コード・テストと要求・設計のトレース・アンカーを埋め込む |
| 5 |
npx musubix3 trace build → npx musubix3 trace check --strict --json → npx musubix3 gate --changed --json
|
実装直後の整合性確認 |
| 6 | npx musubix3 workflow-record sdd-implementation complete --status completed |
このSkillの完了を証跡として一度だけ記録 |
本記事での簡略化について: 手順2・3の
tdd red/tdd greenの記録は、テストランナーにtddArgsとtddReportの設定が必要な、やや踏み込んだ構成です。本記事のデモはqualityProfile: "custom"（デフォルト）を使っており、このtdd証跡はgateではoptional（未設定でもPASSできる）扱いです。そのため、以降の実装パートでは手順2・3のTDD記録は省略し、手順1・4・5のみを実際に行っています。sdd-implementationSkill本来の完全な手順を厳密に踏みたい場合は、tddArgs/tddReportを.musubix/config.jsonに設定した上でtdd red→tdd greenを記録してください（この運用は第3巻・第4巻でより厳格な品質プロファイルとともに扱います）。
設計に基づき、TaskStoreとCLIを実装します（実際にはGitHub Copilot CLIに design.md の内容を渡し、「この設計に基づいてtodo.jsを実装して」と指示してコード生成させる想定）。
// DES-TODO-001: TaskStore component
/** @id CODE-TODO-001
* @implements REQ-TODO-001, REQ-TODO-003, REQ-TODO-004
* @design DES-TODO-001
*/
function addTask(title) { /* ... */ }
function completeTask(id) { /* ... */ }
// DES-TODO-002: CLI component
/** @id CODE-TODO-002
* @implements REQ-TODO-001, REQ-TODO-002, REQ-TODO-003
* @design DES-TODO-002
*/
function main(argv) { /* add/list/done */ }
ポイントは @id / @implements / @design というブロックコメントです。これがコードと要求・設計を紐づける「トレース・アンカー」になります。テスト側にも同様に @verifies を付与します。
/** @id TEST-TODO-001
* @verifies REQ-TODO-001, REQ-TODO-002, REQ-TODO-003, REQ-TODO-004
*/
なお最初にREQ-TODO-002（一覧表示）のテストを「関数を直接呼んで件数を数えるだけ」にしてしまい、node todo.js list の実際の出力（id・title・statusを含むか）は何も検証していない、という抜け漏れがありました。要求のAcceptanceは「出力に何が含まれるか」なので、テストもCLIを子プロセスとして実行し、標準出力を検証する形に直しています。
const { execFileSync } = require('child_process');
// REQ-TODO-002 coverage: `node todo.js list` must print id, title, and status
const output = execFileSync('node', ['todo.js', 'list'], { encoding: 'utf8' });
assert.match(output, /#1 \[open\] write qiita article/,
'REQ-TODO-002: list output includes id, status, title');
注意（本記事のテストの限界）: 上記のCLI子プロセス実行に直したのはREQ-TODO-002のみです。REQ-TODO-001（追加）とREQ-TODO-003（完了）のテストは、
addTask()/completeTask()関数を直接呼び出しており、node todo.js add "..."/node todo.js done <id>という実際のCLI起動そのものは自動テストされていません。要求のAcceptanceが「CLIを実行すると〜」という文言である以上、本来はこの2つもCLI子プロセス経由でテストすべきですが、本記事では紙面の都合上そこまでは踏み込んでいません。実運用では、trace checkはコード・テストとIDの対応関係を検証するものであり、テストの検証内容がAcceptanceの文言を実際にカバーしているかまでは保証しない、という点に注意してください。
動作確認：
$ node todo.js add "buy milk"
added task #1
$ node todo.js add "write qiita article"
added task #2
$ node todo.js list
#1 [open] buy milk
#2 [open] write qiita article
$ node todo.js done 1
completed #1: buy milk
Step 4: トレーサビリティを検証する
自然言語プロンプト→裏側で実行されるコマンド
> 実装が終わったので、トレーサビリティを確認してください。
| # | 裏側で実行されるコマンド | 目的 |
|---|---|---|
| 1 | npx musubix3 trace build |
.musubix成果物とコード中の注釈をスキャンしtrace.jsonを生成 |
| 2 | npx musubix3 trace check --strict --json |
不正なID・リンク切れ・カバレッジ不足を検出 |
| 3 | （影響範囲を調べたい場合）npx musubix3 trace impact REQ-TODO-001 --json
|
ある要求IDの変更がどこまで波及するかを確認 |
| 4 | npx musubix3 workflow-record sdd-traceability complete --status completed |
このSkillの完了を証跡として一度だけ記録 |
要求→設計→コード→テストが @implements / @verifies 注釈で正しくリンクされているかを検証します。
$ npx musubix3 trace build
Trace: 10 nodes, 19 edges, 0 diagnostics.
$ npx musubix3 trace check
PASS / 合格
はじめは @id を書き忘れて TRACE_ANNOTATION_ID エラーになったり、REQ-TODO-002（一覧表示）に対応するテストの注釈が漏れていて TRACE_COVERAGE warningが出たりしました。
注意点として、この trace check が保証するのは「要求・設計・コード・テストが注釈を通じて静的にリンクされている」ことであり、「そのテストが実際に実行されて成功した」ことまでは保証しません（実行結果の検証は後述の gate の commands チェックが担います）。とはいえ「動くコードは書いたが、どの要求に対応するテストなのか誰も分からない」という状態を機械的に検出できる点は、Vibe Codingにはない強みです。
Step 5: 品質ゲートを通す
自然言語プロンプト→裏側で実行されるコマンド
> トレーサビリティも確認できたので、品質ゲートを通してください。
| # | 裏側で実行されるコマンド | 目的 |
|---|---|---|
| 1 |
.musubix/config.json の commands（実行する実テストコマンド）を設定・確認 |
gateのcommands項目が検証対象を認識できるようにする（未設定だとmissing, exit noneになる） |
| 2 |
npx musubix3 gate --json（または--changed --json） |
要求・設計・トレース・承認・実コマンド実行結果などrequired項目を一括検証 |
| 3 | Copilotのネイティブrubber-duckレビュー（releaseの証跡サマリー＋変更内容に対して） |
release承認前の最終チェック。指摘ゼロまで2→3を繰り返す |
| 4 |
npx musubix3 approval prepare release →（承認後）npx musubix3 approval record release --approver <name> --artifact-sha256 <hash> --confirm
|
release承認の提示・記録 |
| 5 |
npx musubix3 gate（再実行） |
releaseが承認されたことを含め、最終PASSを確認 |
| 6 | npx musubix3 workflow-record sdd-quality complete --status completed |
このSkillの完了を証跡として一度だけ記録 |
以下の実行例では、あえて手順1（commands設定）や承認前の状態からgateを実行し、実際にどんな指摘が出るかを先に見た上で、1つずつ直してPASSに至る過程を示します。
最後に、実コマンド実行を含む品質ゲートを回します。
本記事の前提:
musubix3 init直後のqualityProfile: "custom"（デフォルト）では、TDD（Red/Green/Refactor）サイクルの記録やchange-record、mutation、attestationなどは**optional（任意）**として扱われ、未設定でもgateはPASSできます。本巻では最小構成のPASSまでを扱い、これらの厳格な運用（TDDサイクルの証跡化・変更履歴の追跡など）は、より複雑な開発を扱う第3巻・第4巻で掘り下げます。
$ npx musubix3 gate
はじめはこんな指摘がありました。
-
approval [required]: 承認ステージ（requirements/design/release）が揃っていない -
commands [required]: テストコマンドが未設定・未実行
package.json にテストスクリプトを追加した上で、musubix3 config scaffold を実行すると、検出したNode.jsのテストコマンド候補を提案のみしてくれます（config.json を自動で書き換えるわけではありません）。
$ npx musubix3 config scaffold --json
[
{
"toolchain": "node",
"name": "node-tests",
"command": "npm",
"args": ["test"]
}
]
この提案を参考に、.musubix/config.json の commands に手動で反映します（シェル文字列ではなく、command と args を分けた配列形式で書く必要があります）。
"commands": [
{ "name": "node-tests", "command": "npm", "args": ["test"] }
]
反映後、承認ワークフロー（requirements → design → release）を一つずつ通してから再実行すると：
$ npx musubix3 gate
PASS
pass policy [required]
pass requirements [required]
pass design [required]
pass constitution [required]
pass trace [required]
pass graph [required]
pass command:node-tests [required]: npm: completed, exit 0.
pass approval [required]: 3/3 approval stage(s) are current.
pass commands [required]
全required項目がPASS。要求・設計・実装・テスト・承認・品質ゲートが一気通貫でつながった状態です。
📚 もっと知りたい人向け: Spec Kit / AWS Kiro との違い、なぜエンタープライズ開発でmusubix3なのか（クリックで展開）
Spec Kit / AWS Kiro との違い
仕様駆動開発（SDD）× AIコーディングのツールはmusubix3以外にも存在します。代表的な2つと比較します。
| ツール | 提供元 | 主なアプローチ | 特徴 |
|---|---|---|---|
| GitHub Spec Kit | GitHub（OSS） | Specify→Plan→Tasksなどを中心とした標準ワークフロー。各段階でmarkdown成果物を生成しレビューを挟む | 複数のAIコーディングエージェント（Copilot, Claude Code, Cursor等）に対応する汎用ハーネス。コミュニティ提供の拡張でCI/CD・品質ゲートを追加できる（対応エージェント数・拡張数は更新が速いため、最新情報は公式リポジトリを参照） |
| AWS Kiro | AWS | Specs（要求・データフロー・受け入れ基準）を第一級成果物とし、コードはSpecsからの「ビルド成果物」と位置付けるAIエージェントIDE |
.kiro/steering/ による規約の永続化（product.md/tech.mdなど）、.kiro/hooks/ によるファイル保存・PR作成等をトリガーにした自動化 |
| musubix3（本シリーズ） | 個人開発（nahisaho） | GitHub Copilot CLI上で、要求・設計・実装・テストを@implements/@verifies注釈で機械的にリンクし、gateで一括検証 |
「証拠(evidence)重視」。人間の承認をSHA256ハッシュに紐付けて記録（approval record）、改ざん検知の署名（attestation）まで踏み込む点が特徴 |
3つとも「AIに丸投げせず、要求と設計を明文化してからコードを生成する」という思想は共通していますが、重心の置き方が異なります。
- Spec Kitは「複数のAIエージェントをまたぐ標準プロセス」としての汎用性・拡張エコシステムに強みがあります
- AWS Kiroは「IDEに統合されたSpecs/Steering/Hooks」に強みがあり、Kiro上での開発体験を重視するチームに向いています
- musubix3は「承認・トレーサビリティ・証跡の機械検証」に強く踏み込んでおり、"それっぽく通った"を許さない、監査可能性を重視したい場合に向いています
（本比較は各ツールの公開情報に基づく執筆時点でのものです。3ツールとも活発に更新されているため、最新の機能差は各公式ドキュメントを確認してください。）
なぜエンタープライズアプリケーション開発ではmusubix3なのか
個人のTODOアプリ程度なら、どのツールでも大差はありません。しかし、複数チーム・長期保守・監査対応が前提になるエンタープライズアプリケーション開発では、次の3点が決め手になります。
-
「誰が」「何を根拠に」承認したかがハッシュ値で残る
Spec KitやKiroも「仕様をレビューしてから実装する」という工程は用意していますが、musubix3では、その承認行為自体を成果物のSHA256ハッシュに紐付けて記録する（approval prepare/approval record）仕組みが標準で用意されています。SHA256はあくまで「承認時に見た成果物と現在の成果物が同一かどうか」を確認するための完全性識別子であり、それ単体で承認者の本人性までは保証しません。それでも「このバージョンの要求書に、この人が、このタイミングで承認した」という事実をGit管理下の証跡として残せる点は、監査・コンプライアンス対応（第4巻で扱う内容）との相性が良い設計です。 -
証跡の改ざん検知を強化する仕組み（attestation）を追加できる
musubix3 attestationは、Ed25519署名を使って承認やゲート結果に対する署名を作成・検証する機能を提供します。鍵の管理・信頼をどう運用するかという前提は必要ですが、「成果物」だけでなく「成果物が正しく検証されたという記録」自体の真正性を高めたい場合の選択肢になります（他ツールの標準ワークフローで同等の仕組みを筆者は確認できていません）。 -
CIに組み込める「Fail-Closed」な品質ゲート
musubix3 gateは、要求・設計・トレース・承認・実コマンド実行結果など required に指定した項目のすべてが揃っていなければPASSしません（本記事のStep 5で実際に何度もFAILさせています）。「一部だけ確認して残りは省略」を許さないFail-Closed設計は、大規模・複数チーム開発において「レビューの抜け漏れ」がそのまま本番障害につながるリスクを構造的に減らします。
もちろん、Spec Kitの拡張エコシステムやマルチエージェント対応、Kiroの Specs/Steering/Hooks によるIDE体験が必要な場面では、それらの方が適切な選択になり得ます。本シリーズが一貫してmusubix3を採用するのは、「AIコーディングの成果物・プロセス・承認・検証結果までを一つの機械検証可能な証跡チェーンにする」という、エンタープライズのガバナンス要件に直結する特性を、Vol.1〜第4巻で段階的に体験してもらうためです。
まとめ：初学者がハマりやすいポイント
実際にやってみて、初学者がつまずきやすいのは以下の点でした。
-
「承認」を軽視しない: AIが要求や設計を書いても、
approval recordで人間が明示的にsha256付きで承認しないと先に進めない - ADR免除にも理由が要る: 「設計判断なし」と書くにも具体的な理由が必須
-
トレース注釈のIDフォーマット厳守:
@id/@implements/@design/@verifiesの書式を間違えると即エラー -
品質ゲートのcommandsは実際に実行可能な形で登録する: シェル文字列ではなく
{name, command, args}の明示的な配列形式
これらは一見面倒に感じますが、「AIが生成したコードが本当に要求を満たしているか」を人間が確認可能な形で残す、というmusubix3の一貫した思想の表れです。
次巻（第2巻）では、DB連携ありのREST APIを題材に、constitution（測定可能なポリシー）や trace impact（変更影響分析）など、チーム開発での活用を掘り下げます。
シリーズ: GitHub Copilot × MUSUBIX3 によるAI Coding
参考: musubix3 on npm