はじめに（結論ファースト）
人間が仕様書を書くのをやめ、AI に「要求」だけ渡して、仕様策定 → 型定義 → 実装計画 → 実装 → テスト → 監査 までを自走させる開発手法 Rail Coding（レール駆動開発） の運用基盤を OSS として公開しました。
「AI を自由に泳がせない。型と Lint で物理的にレールを敷き、その上を走らせる」 ── kaedevn-monorepo（個人開発のクロスメディア創作プラットフォーム）で実証してきた運用ルールを、他プロジェクトに移植できる形に整理してあります。
本記事は、リポジトリの読み方ガイド＋自分のプロジェクトへの最小導入手順です。
なぜ作ったか — 仕様書の曖昧さが AI を殺す
AI 駆動開発の最大の落とし穴は、人間が不完全な設計書を書き、それを AI に実装させようとすることです。自然言語の仕様書は必ずエッジケース（境界値・非同期競合・例外処理）を見落とし、それが AI の「推測」と「バグ」を生みます。
Rail Coding の前提はシンプルです。
仕様書を書くのをやめる。AI に「型 = 厳密な仕様書」を書かせる。
TypeScript の strict: true は、AI にとってコンパイラが読み上げる仕様書として機能します。型エラーがある状態ではコミットすらできない物理的な壁を作れば、AI は推測で前に進めません。これが「レール」の正体です。
4 本のレール（Guardrails）
Rail Coding が敷く 4 つのレールは以下です。
| # | レール | 物理的な強制方法 |
|---|---|---|
| 1 | 型と Lint の物理強制 | TypeScript strict: true + Biome / oxlint + Husky pre-commit |
| 2 | 2 体の AI による相互監視 | 実装 (Claude Code: The Doer) × 監査 (Gemini CLI: The Auditor / CAO) |
| 3 | 段階的コミットによるコンテキスト同期 | 各フェーズ完了ごとに「コミットして」と指示。git log を AI の地図にする |
| 4 | No-CLI 原則 | 人間がターミナルを叩かない。エラーログも AI に読ませる |
なぜ 2 体の AI が必要か
一人の AI に「書く」と「疑う」を両方させると、必ず自分のコードを擁護します。書く者と疑う者を物理的に分けることでガバナンスが効きます。
-
Claude Code: 実装担当。
src/tests/への書き込み権限あり -
Gemini CLI: 監査担当。書き込みは
docs/以下のレポートのみ。Status: [PASS / WARNING / BLOCK]を出力
6 段階ライフサイクル
各段階の完了後に「コミットして」と指示し、履歴を刻むのが要点です。
要求（人間）
↓
1. 仕様の自律定義 → docs: 仕様定義
↓
2. 基本設計と型駆動 → feat: 型定義とインターフェース
↓
3. 実装計画の自律立案 → docs: 実装計画立案
↓
4. 自律的実装ループ → feat: 実装完了（テスト未実装）
↓
5. テスト仕様策定と実装 → test: ユニット/結合テスト
↓
6. CAO 監査と品質永続化 → docs: 監査完了レポート
人間の出番は (a) 要求を投げる (b) AI が出した成果を承認する (c) 各フェーズで「コミットして」と言う の 3 つだけです。
リポジトリの中身（読む順番）
公開リポジトリは「思想」と「実例」の 2 層構造です。
第 1 層: プレイブック（思想 / 一般化された手順）
docs/playbook/
├── 01_chapter_0-3_setup_and_planning.md # 環境構築〜型駆動設計
├── 02_chapter_4-6_implementation_and_nocli.md # 実装ループ〜No-CLI
├── 03_chapter_appendix_ai_config_and_skills.md # 設定・スキル完全リファレンス
├── column_day1_10k_myth.md # ガードレールなき初日1万行の罠
└── column_ai_perspective.md # AI 監査役から見た真価
第 2 層: AI 連携リファレンス本（実例 26 文書）
つい先ほど統合したばかりの、kaedevn-monorepo 実プロジェクトで Claude Code が単独執筆した詳細リファレンスです。プレイブックの各章を「実装側から見た詳細解説」として補完します。
docs/reports/2026/04/25/
├── 01-guardrails-reproduction.md # ガードレール再現手順
├── 02-guardrails-ts-techniques.md # TS 特有の技法（判別共用体・isolatedModules）
├── 03-typescript-with-genai.md # TS が AI と相性良い理由
├── 04-document-implementation-workflow.md # 設計→計画→実装→テスト
├── 05-rag-search-system.md # pgvector + ハイブリッド検索
├── 06-commit-message-conventions.md # Co-Authored-By + 感想
├── 07-workflow-actual-elapsed-time.md # 計画 14 日 → 実測 4 時間
├── 08-cli-via-ai-prompts.md # No-CLI 原則
├── 09-all-tests-overview.md # 162 + 75 + 89 ケース、6 層
├── 12-mcp-server-implementation.md # MCP サーバー自前実装
├── 13-skill-design-patterns.md # スキル設計パターン
├── 14-claude-code-hooks.md # Hooks による安全弁
├── 15-ai-metadata-api.md # AI Metadata API
├── 16-multi-ai-parallel-dev.md # Multi-AI 並列開発
├── 17-broken-memo-pattern.md # broken-memo パターン
├── 18-devlog-from-git-log.md # devlog 自動生成
├── 19-phase-incremental-pattern.md # Phase 段階実装
├── 20-llm-feature-pipeline.md # LLM 機能パイプライン
├── 21-llm-gateway-abstraction.md # ai-gateway 抽象
├── 22-design-principles-collection.md # 設計原則アンソロジー
├── 23-operations-collection.md # 運用パターン集
├── 24-skills-and-scripts-catalog.md # スキル + スクリプト全カタログ
└── 25-series-index.md # 読む順番ガイド（まずここ）
迷ったら 25-series-index.md を入口にしてください。「最短把握」「AI 連携」「移植」「テスト」「LLM 機能」など、目的別の読む順番が整理されています。
自分のプロジェクトに導入する最小 3 ステップ
Step 1: 物理的なレールを敷く
新規・既存どちらでも、以下のプロンプトを Claude Code に投下します。
「このプロジェクトを Rail Coding 基盤としてセットアップせよ。
tsconfig.jsonをstrict: true,noImplicitAny: trueに設定- Biome（または oxlint）を導入し、推奨ルール全 ON
- Husky で
.husky/pre-commitを作成し、型・Lint エラー時のコミットをブロック- 私が『コミットして』と言ったら Conventional Commits 形式で自動コミットするスキルを整備
完了後npm run typecheckが通ることを確認し『環境構築完了。コミットして。』と私に伝えよ」
Step 2: AI の憲法（CLAUDE.md / GEMINI.md）を書かせる
ルートに CLAUDE.md を作り、4 条程度の「鉄の掟」を入れます（例）。
- 第1条 [Interface First]: 実装前に必ず interface を定義し、承認を得る
- 第2条 [No Direct Access]: UI 層から DB / 外部 API を直接叩かない。Repository 経由
- 第3条 [No Speculation]: 存在しない関数や型を推測で使わない。grep で確認
- 第4条 [No-CLI]: 人間はコマンドを叩かない。Git / Docker / デプロイは AI が実行
Step 3: 段階コミットを習慣化する
各フェーズ完了ごとに必ず「コミットして」と指示する。これだけで git log が AI の地図になり、Gemini が「どのファイルを監査すべきか」を迷わず特定できます。
ハマったポイント
1. ブランチを切ると速度が落ちる
Feature Branch + PR + Merge は人間向けの儀式で、AI の速度を阻害します。main 直 push に振り切り、その代わりに段階コミットを細かく刻むことで、設計が歪んでも 1 フェーズ分（数百行）戻れる安全性を確保しています。
2. AI 監査（BLOCK）を無視すると詰む
Gemini が BLOCK を出した状態で実装を続けると、設計が一気に崩壊します。BLOCK が出たら必ずレポートを Claude に渡し、PASS になるまで修正ループを回す。これを守らないと Rail Coding は単なる速い無秩序開発になります。
3. TypeScript 以外の言語では再現性が落ちる
これは最初に明記しておくべき前提条件です。Python / Ruby など動的型付け言語では「コンパイラが AI を物理的に縛る壁」が弱いため、本プレイブックそのままの再現性は低下します。TypeScript / Rust / Go など静的型付け言語での実践を強く推奨します。
まとめ
Rail Coding の核心は、速度を追い求めることではなく、「設計・テスト・コミット・CLI 操作のすべてを AI に委ねる勇気と、それを支える厳格なレール（型と Lint）」 にあります。
- リポジトリ: https://github.com/mkanakureon/rail-coding-playbook
- まず読むなら:
docs/playbook/01_chapter_0-3_setup_and_planning.md - 実例で深掘るなら:
docs/reports/2026/04/25/25-series-index.md
「AI に任せる勇気」を物理的なガードレールが支える、というのが Rail Coding の発想です。試した結果やフィードバックは Issue / Discussion で歓迎します。
リポジトリの紹介を 1 本にまとめるのは思ったより難しかった。プレイブック側（思想）と 26 文書側（実例）を「両方読んでもらう導線」にするのに頭を使った。シリーズ索引（25 番）を入口に推せたのは個人的に納得感がある。
Claude Opus 4.7