---
description: コードからドキュメント自動生成
---
# Generate Docs Command
TypeScriptコードからAPIドキュメント、README、アーキテクチャ図を自動生成します。
## 使用方法
```bash
/generate-docs [type]
```
## パラメータ
- `type` (オプション): 生成するドキュメントタイプ
- `all` (デフォルト): すべてのドキュメント生成
- `api`: API リファレンス (TypeDoc)
- `readme`: README.md 更新
- `architecture`: アーキテクチャ図生成
- `changelog`: CHANGELOG.md 生成
## 実行内容
### 1. API リファレンス生成 (TypeDoc)
```bash
npx typedoc --out docs/api src/
```
生成されるドキュメント:
```
docs/api/
├── index.html # エントリーポイント
├── classes/
│ ├── BaseAgent.html
│ ├── CoordinatorAgent.html
│ └── CodeGenAgent.html
├── interfaces/
│ ├── Task.html
│ ├── AgentResult.html
│ └── QualityReport.html
├── modules/
│ └── types.html
└── assets/
├── style.css
└── search.js
```
**アクセス**: `open docs/api/index.html`
### 2. README.md 自動更新
コードベースを分析し、README.mdを更新:
```markdown
# Project Name
## 📊 Project Stats
- **Total Files**: 234
- **Lines of Code**: 12,450
- **Test Coverage**: 85%
- **TypeScript**: 100%
- **Dependencies**: 258
## 🏗️ Architecture
<architecture-diagram>
## 📦 Modules
### Core Agents (agents/)
#### CoordinatorAgent
Orchestrates task decomposition and agent assignment.
**Methods**:
- `decomposeIssue(issue: Issue): Promise<TaskDecomposition>`
- `buildDAG(tasks: Task[]): Promise<DAG>`
- `assignAgent(task: Task): Promise<AgentType>`
**Dependencies**:
- Octokit (GitHub API)
- Anthropic SDK
#### CodeGenAgent
Generates code using Claude Sonnet 4.
**Methods**:
- `execute(task: Task): Promise<AgentResult>`
- `generateCode(spec: CodeSpec): Promise<GeneratedCode>`
...
## 📚 API Documentation
Full API documentation: [docs/api/](./docs/api/index.html)
## 🧪 Testing
```bash
npm test # Run tests
npm run test:coverage # With coverage
```
## 📝 Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md)
```
### 3. アーキテクチャ図生成
Mermaid記法でアーキテクチャ図を生成:
#### システム構成図
```mermaid
graph TB
subgraph "User Layer"
U[Human Developer]
end
subgraph "Coordinator Layer"
C[CoordinatorAgent]
end
subgraph "Specialist Layer"
CG[CodeGenAgent]
R[ReviewAgent]
I[IssueAgent]
P[PRAgent]
D[DeploymentAgent]
end
subgraph "External Services"
GH[GitHub]
AN[Anthropic API]
FB[Firebase]
end
U -->|Issue| GH
GH -->|Webhook| C
C -->|Decompose| CG
C -->|Assign| R
C -->|Assign| I
C -->|Assign| P
C -->|Assign| D
CG -->|Generate| AN
D -->|Deploy| FB
P -->|Create PR| GH
```
#### データフロー図
```mermaid
sequenceDiagram
participant User
participant GitHub
participant Coordinator
participant CodeGen
participant Review
participant PR
User->>GitHub: Create Issue with 🤖agent-execute
GitHub->>Coordinator: Webhook trigger
Coordinator->>Coordinator: Decompose into tasks
Coordinator->>CodeGen: Task 1: Implement feature
CodeGen->>CodeGen: Generate code
CodeGen->>Review: Submit for review
Review->>Review: Quality check (≥80)
Review-->>Coordinator: Result (score: 85)
Coordinator->>PR: Create PR
PR->>GitHub: Draft PR created
GitHub->>User: Notification
```
### 4. CHANGELOG.md 生成
Git コミット履歴から自動生成:
```markdown
# Changelog
All notable changes to this project will be documented in this file.
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
## [Unreleased]
### Added
- New feature: User profile editing (#123)
- Agent: DeploymentAgent auto-rollback
### Changed
- Updated lodash to 4.17.21 for security
- Improved CoordinatorAgent DAG algorithm
### Fixed
- Fixed: Login token refresh issue (#124)
- Fixed: Type errors in deployment config
### Security
- Patched XSS vulnerability in UserProfile component
## [1.2.0] - 2025-10-08
### Added
- Agent system implementation
- GitHub Actions integration
- Claude Code optimization
### Changed
- Migrated from JavaScript to TypeScript
- Updated testing framework to Vitest
## [1.1.0] - 2025-09-15
### Added
- Initial agent implementation
- Basic CI/CD pipeline
## [1.0.0] - 2025-09-01
### Added
- Initial release
- Core functionality
```
## 実行例
### Example 1: すべてのドキュメント生成
```bash
/generate-docs all
```
**出力**:
```
📚 Generate Docs - All
1. API Reference (TypeDoc)
⏳ Generating...
✅ docs/api/index.html
📄 234 files documented
🌐 Open: file:///path/to/docs/api/index.html
2. README.md Update
⏳ Analyzing codebase...
✅ README.md updated
📊 Stats: 234 files, 12,450 LOC, 85% coverage
3. Architecture Diagrams
⏳ Generating Mermaid diagrams...
✅ docs/ARCHITECTURE.md
📊 3 diagrams generated
4. CHANGELOG.md
⏳ Analyzing git history...
✅ CHANGELOG.md generated
📝 25 commits processed
✅ Documentation Generated
📂 Output:
- docs/api/ (API Reference)
- README.md (Updated)
- docs/ARCHITECTURE.md (Diagrams)
- CHANGELOG.md (Generated)
🌐 View: open docs/api/index.html
Duration: 1m 23s
```
### Example 2: API ドキュメントのみ生成
```bash
/generate-docs api
```
**出力**:
```
📚 Generate Docs - API Reference
TypeDoc Configuration:
- Entry: src/
- Output: docs/api/
- Theme: default
- Include: README.md
⏳ Generating...
✅ Generated:
- 11 Classes
- 23 Interfaces
- 8 Modules
- 234 Files
📊 Coverage:
- Public APIs: 100%
- JSDoc Comments: 92%
- Examples: 78%
🌐 Open: file:///Users/shunsuke/Dev/Autonomous-Operations/docs/api/index.html
💡 Tip: Add more JSDoc examples for better documentation
```
### Example 3: CHANGELOG のみ生成
```bash
/generate-docs changelog
```
**出力**:
```
📚 Generate Docs - CHANGELOG
Git History Analysis:
- Commits: 125
- Date Range: 2025-09-01 to 2025-10-08
- Contributors: 3
⏳ Generating...
✅ CHANGELOG.md
📝 Releases:
- v1.2.0 (2025-10-08): 45 changes
- v1.1.0 (2025-09-15): 32 changes
- v1.0.0 (2025-09-01): 48 changes
📊 Change Types:
- Added: 18 features
- Changed: 12 improvements
- Fixed: 8 bugs
- Security: 2 patches
🔗 Format: Keep a Changelog
Duration: 12s
```
## TypeDoc 設定
### typedoc.json
```json
{
"entryPoints": ["src/"],
"out": "docs/api",
"theme": "default",
"exclude": [
"**/node_modules/**",
"**/tests/**",
"**/*.test.ts"
],
"excludePrivate": true,
"excludeProtected": false,
"includeVersion": true,
"readme": "README.md",
"plugin": ["typedoc-plugin-markdown"],
"navigation": {
"includeCategories": true,
"includeGroups": true
}
}
```
### package.json
```json
{
"scripts": {
"docs:api": "typedoc",
"docs:serve": "npx http-server docs/api -p 8080 -o"
},
"devDependencies": {
"typedoc": "^0.25.0",
"typedoc-plugin-markdown": "^3.17.0"
}
}
```
## JSDoc ベストプラクティス
### クラスのドキュメント
```typescript
/**
* CoordinatorAgent orchestrates task decomposition and agent assignment.
*
* This agent analyzes GitHub Issues, decomposes them into actionable tasks,
* builds a Directed Acyclic Graph (DAG) for dependency management, and
* assigns appropriate specialist agents to each task.
*
* @example
* ```typescript
* const coordinator = new CoordinatorAgent(config);
* const decomposition = await coordinator.decomposeIssue(issue);
*
* if (!decomposition.hasCycles) {
* for (const task of decomposition.tasks) {
* const agent = await coordinator.assignAgent(task);
* console.log(`Task ${task.id} → ${agent}`);
* }
* }
* ```
*
* @see {@link BaseAgent} for base functionality
* @see {@link docs/AGENT_OPERATIONS_MANUAL.md} for operational details
*/
export class CoordinatorAgent extends BaseAgent {
/**
* Decomposes a GitHub Issue into actionable tasks with dependencies.
*
* Uses Claude Sonnet 4 to analyze the Issue description and extract:
* - Individual tasks
* - Dependencies between tasks
* - Priority and complexity estimates
*
* @param issue - GitHub Issue object
* @returns Task decomposition with DAG
* @throws {Error} If Issue cannot be decomposed
*
* @example
* ```typescript
* const issue = await octokit.issues.get({ issue_number: 123 });
* const decomposition = await coordinator.decomposeIssue(issue);
*
* console.log(`Tasks: ${decomposition.tasks.length}`);
* console.log(`Has cycles: ${decomposition.hasCycles}`);
* ```
*/
async decomposeIssue(issue: Issue): Promise<TaskDecomposition> {
// Implementation
}
}
```
### インターフェースのドキュメント
```typescript
/**
* Quality assessment report for generated code.
*
* Scoring system:
* - Base score: 100
* - ESLint errors: -20 each
* - TypeScript errors: -30 each
* - Critical vulnerabilities: -40 each
*
* Passing threshold: ≥80
*/
export interface QualityReport {
/** Overall quality score (0-100) */
score: number;
/** Whether the code passes quality threshold */
passed: boolean;
/** Detailed breakdown of quality metrics */
breakdown: {
/** ESLint score component */
eslintScore: number;
/** TypeScript type safety score */
typeScriptScore: number;
/** Security vulnerability score */
securityScore: number;
/** Test coverage score */
testCoverageScore: number;
};
/** List of identified quality issues */
issues: QualityIssue[];
/** Recommendations for improvement */
recommendations: string[];
}
```
## Mermaid 図の種類
### 1. フローチャート
```mermaid
flowchart TD
A[Start] --> B{Error?}
B -->|Yes| C[Log Error]
B -->|No| D[Process Data]
C --> E[End]
D --> E
```
### 2. シーケンス図
```mermaid
sequenceDiagram
User->>Agent: Execute task
Agent->>API: Call external API
API-->>Agent: Return data
Agent-->>User: Task completed
```
### 3. クラス図
```mermaid
classDiagram
class BaseAgent {
+execute(task: Task)
+validateTask(task: Task)
+escalate(reason: string)
}
class CoordinatorAgent {
+decomposeIssue(issue: Issue)
+buildDAG(tasks: Task[])
}
BaseAgent <|-- CoordinatorAgent
```
### 4. ER図
```mermaid
erDiagram
ISSUE ||--o{ TASK : contains
TASK ||--|| AGENT : "assigned to"
TASK ||--o{ DEPENDENCY : has
ISSUE {
int number
string title
string body
}
TASK {
string id
string type
string status
}
```
## CI/CD統合
### GitHub Actions で自動生成
```yaml
name: Generate Docs
on:
push:
branches: [main]
workflow_dispatch:
jobs:
generate-docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node.js
uses: actions/setup-node@v3
with:
node-version: '20'
- name: Install dependencies
run: npm ci
- name: Generate API docs
run: npm run docs:api
- name: Deploy to GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
publish_dir: ./docs/api
```
## トラブルシューティング
### Q1: TypeDoc がエラーを出す
```bash
# TypeDoc を最新版に更新
npm update typedoc
# キャッシュクリア
rm -rf node_modules/.cache
```
### Q2: Mermaid 図が表示されない
GitHub で Mermaid を表示するには、markdown ファイルに以下を追加:
````markdown
```mermaid
graph TD
A --> B
```
````
### Q3: CHANGELOG が空
```bash
# Conventional Commits形式を確認
git log --oneline
# feat:, fix: などの接頭辞が必要
```
## 関連ドキュメント
- [TypeDoc Documentation](https://typedoc.org/)
- [Mermaid Documentation](https://mermaid.js.org/)
- [Keep a Changelog](https://keepachangelog.com/)
- [JSDoc Documentation](https://jsdoc.app/)
---
📚 定期的なドキュメント生成でプロジェクトを最新に保ちましょう。
