Claude Codeによるドキュメントとプログラムの相互開発
常に最新化されたドキュメントがほしい・・・！
Web界隈で働いていると誰もが思ったことのあるテーマではないでしょうか。リソースも知恵も豊富にあるイケてるスタートアップだといろいろできるのでしょうが、そうではない多くの人たちの役に立つかもしれない開発手法のメモです。（主にWeb開発を想定しています）
適切なドキュメントがあると何ができるのか
以下のようなことをこれまでより高精度に行うことができます。
AIツールの情報ソースとして活用
Geminiなど各種AIツールの情報ソースとして利用し、仕様に関する問い合わせにこれまでより正確に回答してもらう。社内対応にも顧客対応にも活用可能。
実際の仕様に基づいた正確な回答
今後の開発企画、マーケティング企画について叩き台を作ってもらう。
今後の開発企画、マーケティング企画について叩き台を作ってもらう。機能的な提案から運営的な提案まで様々。
機能的な提案から運営的な提案まで様々
オウンドメディア用の記事や営業資料などを作成してもらう
オウンドメディア用の記事や営業資料などを作成してもらう。現状に基づく正確で専門的な記事をどんどん作ってもらえる。
現状に基づくかなり正確な記事をどんどん作ってもらえる指示
業務改善視点の記事を書いたり
技術にフォーカスした記事を書いたり
「ドキュメント」の役割と特性が変化している
これまで
- プログラムのおまけ、更新漏れは仕方のないもの
- 更新コストに見合わない参照頻度
- 書き手のスキルに依存する曖昧性
- エンジニア以外にも向けた、人間のためだけの情報
現在
- 企画、設計、開発、運用、マーケティング…全てのフェーズにおける礎
- コードベースを元にした正確で継続的に更新された最新情報
- AI-Driven Developmentにおける開発指針
AI Drivenな開発にはもちろん、サービス開発全体のフローに大きな影響を与えることができます。新規開発だけでなく、すでにあるプロダクトへの導入も簡単。
実際の進め方
ここではClaude Code（Opus 4）を利用した手法を紹介します。プロジェクトによって適切なドキュメント類や作り方は変わると思いますが、一般的に中規模程度のWebサービスを想定しています。
1. overview.md（プロジェクト概要）の作成
まずはそのプロジェクトがどういうものかを簡単に整理します。新規プロジェクトであればAIも活用しつつ整理。既存プロジェクトであればClaude Codeで「このプロジェクトの概要などについてまとめたドキュメントをmarkdownで作成してください。このサービスのことを正確に理解させつつ、魅力が十分に伝わる構成にしてください。」といった、ざっくりとした指示でも意図に近いものが出てくるのではないかと思います。
# ○○サービス概要
## 🎯 ○○とは
**○○**は、企業のコーポレート部門（総務・人事など）向けに設計された**社員のメンタル状況管理SaaS**です。
, ... (サービス説明)
## 💡 解決する課題
### コーポレート部門が抱える悩み
~
### 主要機能
~
...
2. features.md（機能一覧）の作成
overview.mdや、その他プロジェクトに関する情報があればそれを渡しながらfeatures.mdの作成を指示します。「overview.mdにこのプロジェクトに関する情報が記載されています。その情報を元に機能一覧を作成してください。」などざっくりから始めて、何度かやりとりしているとかなり具体的なドキュメントになっていくと思います。
# 〇〇機能一覧
〇〇は、社員のメンタル状況把握をサポートする SaaS アプリケーションです。
## 認証・ユーザー管理
- [x] **Supabase Auth認証基盤**
- メールアドレス/パスワードでのログイン・会員登録
- 会員登録/ログイン切り替え可能な統合フォーム
- メール確認機能（確認リンク送信）
- Auth callbackルートでのメール確認処理
- セッション管理とミドルウェアによる保護
- [x] **オンボーディングフロー**
- 初回登録時のユーザー名・組織名設定
- 自動的に管理者権限を付与
- Admin Clientを使用したRLSバイパス処理
- Server Actionsによるフォーム処理
- [x] **マルチテナント対応**
- テナント単位でのデータ分離（RLS）
- テナント作成・管理
- tenant_usersテーブルでの関連管理
- [x] **ロール管理**
- ADMIN（管理者）/ MEMBER（メンバー）の2種類
- 定数管理による型安全な実装（USER_ROLES）
- RLSポリシーによるロールベースアクセス制御
- 共通認証ヘルパーによる統一的な権限チェック
#### 基盤機能
- [x] **Next.js 15 App Router**
- Server Components中心のアーキテクチャ
, ...
3. architecture.md（構成・設計）の作成
overview.md、features.mdなどこれまでのドキュメント、情報をもとにアーキテクチャを考えてもらいます。技術選定などは会社やプロジェクトにより様々な条件があると思うので、それらを指示に含めつつブラッシュアップしていきます。選定技術、ディレクトリ構成、主要なテーブル構成、認証であったり影響範囲が広い部分のコーディングルールを記載しています。
# ○○ Architecture Documentation
## 📋 Overview
○○は、企業のコーポレート部門向けに設計された社員のメンタル状況管理SaaSです。Next.js 15のServer Components、Vercel、Supabase、shadcn/uiを活用し、モダンでスケーラブルなアーキテクチャを実現します。
## 🏗️ Technology Stack
### Core Technologies
- **Frontend Framework**: Next.js 15 (App Router, Server Components中心)
- **Hosting**: Vercel (Edge Runtime対応)
- **Database & Auth**: Supabase (PostgreSQL, Auth)
, ...
## 📁 Project Structure
project/
├── app/ # Next.js App Router
│ ├── (public)/ # 認証不要のページ
│ │ ├── layout.tsx # 公開ページレイアウト
, ...
## 🗄️ Database Architecture
### Supabase Schema Design
> **Note**: 以下のスキーマは初期設計のサンプルです。
```sql
-- 主要なテーブル構造の概要
-- 詳細は database-schema.md を参照
-- テナント管理
CREATE TABLE tenants (...);
-- ユーザー（Supabase Auth連携）
CREATE TABLE users (...);
,...
4. mvp-business.md（MVP戦略）、mvp-develop-tasks.md（MVP開発タスクリスト）の作成など
ここまででサービスの概要、システムの構築の方針などを整理してきました。自分の場合は、考えられる機能を全て洗い出し、その上でMVP戦略などこれからの開発計画を組ませています。より具体的な開発タスクがチェックリスト形式で作れるので、あとは順番にClaude Codeと実装していくことになります。
# 〇〇 MVP 概要（ビジネス層向け）
## 🎯 MVPで実現すること
### できるようになること
1. **ユーザー登録・ログイン**
- メールアドレスまたはGoogleアカウントで登録・ログイン可能
- 複数の会社・ブランドを切り替えて管理（マルチワークスペース）
, ...
# 〇〇 MVP開発計画
## 概要
本計画書は、〇〇開発の詳細計画です。
全体を4つのフェーズに分け、段階的にリリースしていきます。
## 開発方針
- **フェーズ型開発**: 各フェーズ完了時点でデプロイ可能な状態を維持
- **TDD（テスト駆動開発）**: 全ての機能実装前にテストを作成
- **ユーザーフィードバック重視**: 各フェーズ後にフィードバックを収集し改善
## フェーズ概要
### 🚀 Phase 1: Foundation（基盤構築）
**期間**: 2週間
**目標**: 基本的な投稿・閲覧機能の実装
### 📱 Phase 2: Core Features（コア機能）
**期間**: 3週間
**目標**: ユーザー体験の核となる機能の実装
### 🎨 Phase 3: Enhancement（機能強化）
**期間**: 2週間
**目標**: ユーザビリティとエンゲージメント向上
### 🏁 Phase 4: Launch Ready（リリース準備）
**期間**: 1週間
**目標**: プロダクションリリースの準備
---
## Phase 1: Foundation（基盤構築）- 2週間
### Week 1: インフラ・認証基盤
#### Day 1-2: プロジェクトセットアップ
- [ ] Next.js 15プロジェクト作成
- [ ] TypeScript設定（strict mode）
- [ ] Tailwind CSS, shadcn設定
- [ ] ESLint/Prettier設定
- [ ] Vitest設定
,...
5. CLAUDE.mdの更新
実装の際にこれまでの主要ドキュメントを常に参照・更新してもらうように指示を書いておきます。コンテキストが膨らむと指示が無視されることもありますが、定期的に依頼すれば常に最新状態のドキュメントを参照しつつコードの更新、更新されたコードを参照しつつドキュメントの更新、という相互開発が回ることになります。
## 実装の基本方針
architecture.mdを参照し、ベースとなるアーキテクチャから逸れないようにしてください。
, ...
## 🎯 品質チェックリスト
コード生成時は以下を確認：
- [ ] Server Componentがデフォルトになっているか
- [ ] **関連ドキュメントは更新されているか**
, ...
ドキュメントの展開
冒頭に戻りますが、これらのドキュメントを情報ソースとしてチャットbotを作ったりコンテンツをAIに作ってもらったりすると、これまでよりかなり精度が高いものを作ることができます。また、現状を元にこれからの企画の叩き台を作るなども、なんとなくAIに考えさせるより具体的で現実味のある提案が多いです。更新されたドキュメントを各ツールに連携するところも自動化して、常に最新ドキュメントで社内の業務が回る体験、いかがでしょうか。
まとめ
ドキュメントが常に最新であり、社内の情報連携もある程度自動化されていると、こんなにも事務的な業務が減り社内全体がそれぞれの専門領域に専念できるんだと、とても効果を感じた運用でした。もっとこうすると良いなどの改善案もお待ちしております。Xではもっと気楽に発見をつぶやきます。@taroudev
Discussion