AI主導開発前提でのGithub Issueとdocs/以下の棲み分け Claude案

Posted at 2025-08-23

プロジェクトドキュメント運用ガイド

📁 ディレクトリ構造

/
├── README.md           # プロジェクト概要（人間向け入口）
├── CLAUDE.md          # AI開発コンテキスト
├── docs/
│   ├── 00-overview/   # 全体像（人間の理解の起点）
│   │   ├── introduction.md      # このシステムは何か
│   │   ├── features.md          # 機能一覧とステータス
│   │   └── architecture.md      # システム構成概要
│   ├── 10-guides/     # 使い方ガイド（順序重要）
│   │   ├── 01-setup.md         # 環境構築
│   │   ├── 02-development.md   # 開発の始め方
│   │   └── 03-deployment.md    # デプロイ方法
│   ├── 20-features/   # 機能詳細仕様
│   │   └── [機能名]/
│   │       ├── README.md       # 機能概要
│   │       ├── design.md       # 詳細設計
│   │       └── api.md          # API仕様
│   └── 30-decisions/  # 技術的意思決定
│       └── YYYY-MM-DD-[決定内容].md
└── .ai/               # AI作業用（.gitignore対象）
    └── session.md     # 現在の作業コンテキスト

📝 各ファイルの詳細仕様

/README.md

# [プロジェクト名]

## 概要
[1-2文でプロジェクトを説明]

## クイックスタート
```bash
git clone https://github.com/[org]/[repo]
cd [repo]
npm install
npm run dev

ドキュメント

ライセンス

[ライセンス情報]


### /CLAUDE.md
```markdown
# AI Development Context

## Project Overview
[プロジェクトの技術的な説明 1-2文]

## Tech Stack
- Language: TypeScript 5.x
- Runtime: Node.js 20.x
- Framework: Express.js
- Database: PostgreSQL 15
- Cache: Redis

## Project Structure
\`\`\`
src/
├── api/          # APIエンドポイント定義
├── services/     # ビジネスロジック
├── models/       # データモデル
├── utils/        # 共通ユーティリティ
└── types/        # TypeScript型定義
\`\`\`

## Key Conventions
- **API**: RESTful, /api/v1/* prefix
- **Error Format**: `{ error: { code: string, message: string } }`
- **Authentication**: JWT Bearer token in Authorization header
- **Date/Time**: Always UTC, ISO 8601 format
- **Testing**: Jest for unit tests, Supertest for API tests

## Active Development
### Current Sprint (2024-01-23)
- [ ] #235: 決済システム統合 → [設計書](docs/20-features/payment/)
- [ ] #240: 通知システム → [設計書](docs/20-features/notification/)
- [ ] #245: パフォーマンス改善

### Known Issues
- #256: メモリリーク調査中
- #257: DBコネクションプール最適化

## Important Documentation
- [アーキテクチャ概要](docs/00-overview/architecture.md)
- [API設計ガイドライン](docs/30-decisions/2024-01-01-api-design.md)
- [デプロイ手順](docs/10-guides/03-deployment.md)

## Development Commands
\`\`\`bash
npm run dev          # 開発サーバー起動
npm test            # テスト実行
npm run build       # ビルド
npm run migrate     # DBマイグレーション
npm run lint        # Linter実行
\`\`\`

## Environment Variables
\`\`\`bash
DATABASE_URL=postgresql://...
REDIS_URL=redis://...
JWT_SECRET=...
NODE_ENV=development|production
\`\`\`

/docs/00-overview/features.md

# 機能一覧

最終更新: 2024-01-23

## ✅ 実装済み機能

### ユーザー認証
- **ステータス**: Stable
- **バージョン**: v1.0
- **詳細**: [→ authentication](../20-features/authentication/)
- **API**: `/api/v1/auth/*`
- **最終更新**: 2024-01-10

### ユーザープロファイル
- **ステータス**: Stable
- **バージョン**: v1.0
- **詳細**: [→ user-profile](../20-features/user-profile/)
- **API**: `/api/v1/users/*`
- **最終更新**: 2024-01-05

## 🚧 開発中機能

### 決済システム
- **ステータス**: In Development
- **予定バージョン**: v1.1
- **Issue**: #235
- **詳細**: [→ payment](../20-features/payment/)
- **担当**: @developer1
- **予定**: 2024-02-01

### 通知システム
- **ステータス**: Design Phase
- **予定バージョン**: v1.2
- **Issue**: #240
- **詳細**: [→ notification](../20-features/notification/)
- **担当**: @developer2

## 📋 計画中機能

### レポート機能
- **Issue**: #250
- **優先度**: Medium
- **予定**: 2024 Q2

### 管理画面
- **Issue**: #251
- **優先度**: Low
- **予定**: 2024 Q3

---
*注: 新機能追加時は必ずこのファイルを更新してください*

/docs/20-features/[機能名]/README.md テンプレート

# [機能名]

## 概要
**ステータス**: Draft | In Development | Stable | Deprecated
**Issue**: #[番号]
**担当**: @[username]
**最終更新**: YYYY-MM-DD

[機能の簡潔な説明]

## ユースケース
- [誰が]
- [何を]
- [なぜ]

## 技術設計

### アーキテクチャ
[設計図や説明]

### データモデル
\`\`\`typescript
interface [ModelName] {
  id: string;
  // ...
}
\`\`\`

### API エンドポイント
- `POST /api/v1/[resource]` - [説明]
- `GET /api/v1/[resource]/:id` - [説明]

詳細: [API仕様](./api.md)

## 実装チェックリスト
- [ ] データモデル定義
- [ ] API実装
- [ ] ユニットテスト
- [ ] 統合テスト
- [ ] ドキュメント更新

## 関連ドキュメント
- [全体アーキテクチャ](../../00-overview/architecture.md)
- [API設計ガイドライン](../../30-decisions/2024-01-01-api-design.md)

/docs/30-decisions/YYYY-MM-DD-[決定内容].md テンプレート

# [決定タイトル]

**日付**: YYYY-MM-DD
**ステータス**: Accepted | Superseded | Deprecated
**Issue**: #[番号]（もしあれば）

## コンテキスト
[なぜこの決定が必要になったか]

## 決定
[何を決定したか]

## 理由
[なぜこの選択をしたか]

## 検討した代替案
1. **[代替案1]**: [却下理由]
2. **[代替案2]**: [却下理由]

## 影響
- **メリット**: 
  - [メリット1]
  - [メリット2]
- **デメリット**: 
  - [デメリット1]
  - [デメリット2]

## 参考資料
- [リンク1]
- [リンク2]

🔄 運用フロー

新機能開発フロー

具体的なコマンド例

# 1. 新機能のIssue作成後
mkdir -p docs/20-features/email-notification
cp docs/templates/feature-template.md docs/20-features/email-notification/README.md

# 2. features.md更新
vim docs/00-overview/features.md
# "開発中機能" セクションに追加

# 3. CLAUDE.md更新
vim CLAUDE.md
# "Active Development" に追加: 
# - [ ] #280: メール通知 → [設計書](docs/20-features/email-notification/)

# 4. Claude Codeで開発
claude-code "Issue #280 のメール通知機能を実装"

# 5. 完了後、ステータス更新
# features.md: "開発中" → "実装済み" へ移動
# CLAUDE.md: Active Development から削除

🤖 AIとの協働

AIが参照する優先順位

CLAUDE.md - 現在のコンテキスト
docs/20-features/ - 作業中の機能仕様
docs/30-decisions/ - 設計判断の背景
GitHub Issue - 追加の文脈

AIへの指示例

# 単純なバグ修正
claude-code "Issue #290を修正"

# 設計書がある機能開発
claude-code "docs/20-features/payment/の設計に基づいて決済機能を実装"

# 調査タスク
claude-code "Issue #295のパフォーマンス問題を調査し、結果をdocs/30-decisions/に記録"

👥 人間の参照パス

新規参加者

README.md → プロジェクト概要
docs/00-overview/introduction.md → 詳細説明
docs/10-guides/01-setup.md → 環境構築
docs/10-guides/02-development.md → 開発開始

機能を理解したい

docs/00-overview/features.md → 機能一覧
docs/20-features/[機能名]/ → 詳細仕様

設計背景を知りたい

docs/30-decisions/ → 意思決定記録

🔧 自動化スクリプト

scripts/new-feature.sh

#!/bin/bash
# 新機能のドキュメントテンプレート生成

FEATURE_NAME=$1
ISSUE_NUMBER=$2

if [ -z "$FEATURE_NAME" ] || [ -z "$ISSUE_NUMBER" ]; then
    echo "Usage: ./scripts/new-feature.sh <feature-name> <issue-number>"
    exit 1
fi

# ディレクトリ作成
mkdir -p "docs/20-features/${FEATURE_NAME}"

# テンプレートコピー
cp docs/templates/feature-template.md "docs/20-features/${FEATURE_NAME}/README.md"

# Issue番号を置換
sed -i "s/#\[番号\]/#${ISSUE_NUMBER}/g" "docs/20-features/${FEATURE_NAME}/README.md"
sed -i "s/\[機能名\]/${FEATURE_NAME}/g" "docs/20-features/${FEATURE_NAME}/README.md"

echo "Created: docs/20-features/${FEATURE_NAME}/"
echo "Next steps:"
echo "1. Edit docs/20-features/${FEATURE_NAME}/README.md"
echo "2. Update docs/00-overview/features.md"
echo "3. Update CLAUDE.md Active Development section"

.github/workflows/docs-check.yml

name: Documentation Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      
      - name: Check for new features without docs
        run: |
          # src/に新機能追加を検出
          if git diff --name-only origin/main..HEAD | grep -q "^src/.*\.ts$"; then
            # 対応するdocs更新を確認
            if ! git diff --name-only origin/main..HEAD | grep -q "^docs/"; then
              echo "::warning::新機能が追加されていますが、ドキュメントが更新されていません"
              echo "::warning::docs/20-features/ または docs/00-overview/features.md の更新を検討してください"
            fi
          fi
      
      - name: Validate feature status
        run: |
          # features.mdの整合性チェック
          python scripts/validate-features.py

📋 チェックリスト

Issue作成時

適切なラベル付与（bug, feature, documentation等）
マイルストーン設定
担当者アサイン

機能開発開始時

docs/20-features/[機能名]/ 作成
docs/00-overview/features.md 更新
CLAUDE.md の Active Development 更新

PR作成時

関連Issue番号記載
ドキュメント更新確認
テスト追加/更新

機能完了時

features.md のステータス更新
CLAUDE.md から削除
必要に応じて decisions/ に記録

🎯 成功の指標

新規参加者が1時間以内に開発開始できる
AIが正確に機能実装できる
3ヶ月前の設計判断の理由がすぐわかる
ドキュメントの更新漏れが月1件以下

このガイドは定期的に見直し、プロジェクトの成長に合わせて更新してください

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up