はじめに

この記事では、私が作成した開発ワークフロー管理ツール「slash-commands」について紹介します。これは、AI支援によってドキュメント駆動開発を実践し、小規模チームでも大規模プロジェクト並みの品質管理を実現するためのツールです。

リポジトリ: https://github.com/tkysi-mi/slash-commands

なぜこのツールを作ったのか

既存ツールとの出会いと課題

私はこれまで、様々なドキュメント駆動開発ツールを使ってきました：

Spec Kit (GitHub): 仕様駆動開発のフレームワーク
Super Claude: Claude Codeの拡張
BMAD (BMAD Method): マルチエージェント開発プロセス
Claude Code / Windsurf: AI支援コーディング環境

これらのツールはそれぞれ素晴らしいのですが、使っているうちにいくつかの課題を感じるようになりました：

コンテキスト管理の制御が不十分: AIに渡すコンテキストを細かく制御できない
リポジトリ構造の自由度が低い: ツールの想定する構造に縛られる
自分の開発スタイルとのミスマッチ: 理想的なワークフローを実現できない

「理想」を実現したかった

私には「こうプロジェクトを運営したい」という理想のワークフローがありました。しかし、これまではリソース不足（時間・人員・予算）により、その理想を実践することは不可能でした。

要件定義からドメインモデル、設計まで体系的にドキュメント化したい
すべてのタスクに対して、定義→リサーチ→実装計画→実装という流れを徹底したい
ドキュメント間の一貫性を保ちたい
計画と実装の差異を記録し、振り返りたい

でも、待てよ。AIがあれば、これができるんじゃないか？

そう気づいたとき、既存ツールを使うのではなく、自分の理想のワークフローを実現するツールを作ろうと決めました。

slash-commandsとは何か

基本コンセプト

slash-commandsは、Windsurf（またはClaude Code）で使用するスラッシュコマンド形式のワークフロー定義集です。実行可能コードは一切含まず、すべてMarkdownファイルで構成されています。

核心的なアイデアは次の通りです：

AIの支援により、1-2人の小規模チームでも、従来は大企業でしか維持できなかったレベルの包括的ドキュメントを維持できる

4つのワークフロー系列

開発ライフサイクル全体を4つの系列でカバーします：

A系列: プロジェクト設計ワークフロー（14個）

プロジェクト開始時に一度だけ実行。要件定義からアーキテクチャ設計まで。

a-001: ドキュメント構造セットアップ
a-002: プロジェクト初期化
a-003: シナリオ定義（BDD/Gherkin）
a-004: ドメインモデル定義（Event Storming）
a-005: ドメイン図作成（DDD）
a-006: 要件・ドメインレビュー ⭐
a-007: 技術スタック選定
a-008: リポジトリ構造定義
a-009: 画面設計
a-010: データモデル設計（ERD）
a-011: API仕様定義
a-012: アーキテクチャ設計（ADR）
a-013: インフラ設計
a-014: 設計レビュー ⭐

B系列: タスク管理ワークフロー（5個）

各機能開発時に実行。タスクの定義から実装計画まで。

b-000: タスクディレクトリ作成
b-001: タスク定義（目的、ユーザーストーリー、受け入れ基準）
b-002: リサーチ（ベストプラクティス、既存コード調査）
b-003: 実装計画（フェーズ、ステップ、成果物）
b-004: タスクレビュー ⭐

C系列: 実装実行ワークフロー（2個）

実装とドキュメント更新。

c-001: 実装実行（spec-kitスタイル）
c-002: ドキュメント更新（実装完了後）

X系列: 補助的なワークフロー（17+個）

実装中に必要となる補助タスク。Object-Action命名規則。

x-Context-CatchUp: プロジェクト状況把握
x-Requirements-Clarify: 要件明確化
x-Code-Refactor: リファクタリング
x-CI-Setup: CI/CD構築
x-Repository-Push: GitHub/GitLabプッシュ
...など

3つのレビュー「ゲート」

品質を保証する3つのチェックポイント：

レビュー	タイミング	対象	効果
a-006	要件・ドメイン完成時	要件 ↔ シナリオ ↔ ドメインモデル	ドメイン設計の妥当性検証
a-014	設計完成時	データモデル ↔ API ↔ 画面 ↔ アーキテクチャ	設計の一貫性検証
b-004	各タスク実装前	タスク定義 ↔ リサーチ ↔ 実装計画	実装漏れ防止

これらのレビューワークフローは、AIが自動でドキュメント間の一貫性をチェックし、不整合があれば警告・エラーとして報告します。

実際の開発フロー

プロジェクト開始時（1回のみ）

┌─────────────────────────────────────────┐
│ A系列: プロジェクト設計                    │
├─────────────────────────────────────────┤
│ a-001 〜 a-005: 要件・ドメイン定義         │
│ a-006: レビュー ⭐                        │
│ a-007 〜 a-013: 設計                     │
│ a-014: レビュー ⭐                        │
└─────────────────────────────────────────┘

/a-001-SetupDocStructure を実行してドキュメント構造を作成
/a-002 〜 /a-005 で要件とドメインモデルを定義
/a-006-ReviewRequirementsDomain でレビュー（ここで不整合を修正）
/a-007 〜 /a-013 で技術選定から設計まで実施
/a-014-ReviewDesign でレビュー（設計ドキュメント間の一貫性確認）

各機能開発時（タスクごとに繰り返し）

┌─────────────────────────────────────────┐
│ B系列: タスク管理                         │
├─────────────────────────────────────────┤
│ b-000 〜 b-003: 計画                     │
│ b-004: レビュー ⭐                        │
└─────────────────────────────────────────┘
              ↓
┌─────────────────────────────────────────┐
│ C系列: 実装実行                           │
├─────────────────────────────────────────┤
│ c-001: 実装                              │
│ c-002: ドキュメント更新                   │
└─────────────────────────────────────────┘

/b-000-CreateTaskDirectory でタスクディレクトリ作成（自動採番: task000001, task000002...）
/b-001-CreateTaskDefinition で目的・ユーザーストーリー・受け入れ基準を定義
/b-002-CreateTaskResearch でベストプラクティス調査、既存コード分析
/b-003-CreateTaskImplementation で実装計画（フェーズ、ステップ、成果物）
/b-004-ReviewTask でレビュー（実装開始前の最後の砦）
/c-001-ImplementTask で実装実行（spec-kitスタイルで段階的に）
/c-002-UpdateDocumentation でドキュメント更新（計画と実装の差異を記録）

実装中（随時）

X系列のワークフローを必要に応じて使用：

コードをリファクタリングしたい → /x-Code-Refactor
CI/CDをセットアップしたい → /x-CI-Setup
GitHubにプッシュしたい → /x-Repository-Push

なぜMarkdownだけなのか

このツールには実行可能コードが一切ありません。すべてMarkdownファイルです。理由は：

1. コンテキスト制御の最適化

Windsurfのコンテキストウィンドウには制限があります（約12,000文字）。Markdownファイルなら、必要なワークフローだけを @.windsurf/workflows/x-Code-Refactor.md のように参照することで、コンテキストを最小限に保てます。

2. 柔軟性とカスタマイズ性

各プロジェクトで自由に編集可能
フレームワーク非依存（React/Vue/Svelte、Prisma/TypeORM、Webpack/Viteなど）
自分のワークフローに合わせて改変できる

3. メンテナンス性

バージョン管理が容易（Gitで差分確認）
テキストなので検索・置換が簡単
AIがMarkdownを理解・生成するのに最適

設計思想とベストプラクティス

仕様駆動開発（Spec Kit風）

c-001（実装実行ワークフロー）はGitHubのSpec Kitにインスパイアされています：

タスク定義とリサーチが「実行可能な仕様」として機能
各ステップは1-3時間粒度で定義
依存関係を尊重し、[P]マークで並列実行を最適化
各ステップでテストを実行し、受け入れ基準を確認

ドキュメント間の一貫性維持

従来のドキュメント駆動開発の最大の課題は「ドキュメントが古くなる」ことでした。このツールでは：

レビューワークフローで事前チェック: 実装前にドキュメント間の不整合を検出
c-002で事後更新: 実装後に計画と実装の差異を記録し、ドキュメントを更新

AI支援による効率化

重要なパラダイムシフト：

従来: 1-2人チームでは包括的ドキュメントは維持不可能
AI支援: 小規模チームでも企業レベルのドキュメント品質を維持可能

AIが文章作成の重荷を負う
人間は意図と判断を提供
システムが一貫性を保証

実際に使ってみた感想

正直に言うと、まだこのシステムで多くのプロジェクトを運用したわけではありません。しかし、初期の使用感は非常に良好です：

良い点

計画の抜け漏れが減った: b-004レビューで実装前に問題を検出できる
ドキュメントが生きている: c-002で実装後に更新する習慣ができた
自分のペースで進められる: 必要なワークフローだけを使える
フレームワーク非依存: どんなプロジェクトでも使える

改善の余地

学習曲線: 最初は14個のa系列ワークフローが多く感じる
小規模プロジェクトには過剰かも: MVPレベルではB系列とC系列だけで十分かもしれない
まだ実験段階: 本番プロジェクトでの検証が必要

今後の展望

オープンソースだけど...

現在、このツールはGitHubで公開しており、誰でも自由に使えます。ただし：

将来的にクローズする可能性もあります: まだ実験段階なので
アップデート頻度は不定期: 個人プロジェクトなので
コントリビューションは歓迎: フィードバックやPRは大歓迎です

こんな人に使ってほしい

AI支援開発を活用したい個人開発者・小規模チーム
ドキュメント駆動開発に興味がある人
既存のツール（Spec Kit、Super Claudeなど）を使ってみたけど、もっとカスタマイズしたい人
「理想のワークフロー」を持っているけど実践できていない人

使い方のコツ

最初から全部使おうとしない: X系列から試すのもアリ
自分のプロジェクトに合わせてカスタマイズ: Markdownなので自由に編集
小さく始める: B系列 → C系列 → A系列の順で導入するのもOK

まとめ

slash-commandsは、私が「こうプロジェクトを運営したい」という理想を、AIの力を借りて実現するために作ったツールです。

従来は不可能だった「小規模チームでの包括的ドキュメント管理」が、AIによって現実的になりました。Spec KitやSuper Claude、BMADなど様々なツールから学び、自分のワークフローに最適化した結果がこのツールです。

まだ実験段階ですが、同じような課題を感じている方がいれば、ぜひ試してみてください。そして、フィードバックをいただけると嬉しいです。

リポジトリ: https://github.com/tkysi-mi/slash-commands

動作環境: Windsurf

ライセンス: MIT（現時点）

この記事が、AI時代の開発ワークフローを考えるきっかけになれば幸いです。