ドキュメンテーション テンプレート

一般的なドキュメンテーション形式の構造ガイドラインとテンプレート。

---

1. README の構造

必須セクション（優先順）

セクション	目的
タイトル + 一行説明	これは何か？
クイックスタート	5分以内で実行
機能	何ができるか？
設定	カスタマイズ方法
API リファレンス	詳細ドキュメントへのリンク
貢献方法	どうやって手伝うか？
ライセンス	法的情報

README テンプレート

# Project Name

簡潔な一行説明。

## Quick Start

[実行に必要な最小限のステップ]

## Features

- 機能 1
- 機能 2

## Configuration

| 変数 | 説明 | デフォルト |
|----------|-------------|---------|
| PORT | サーバーポート | 3000 |

## Documentation

- API Reference
- Architecture

## License

MIT

---

2. API ドキュメンテーション構造

エンドポイントごとのテンプレート

## GET /users/:id

ID でユーザーを取得します。

**パラメータ:**
| 名前 | 型 | 必須 | 説明 |
|------|------|----------|-------------|
| id | string | Yes | ユーザー ID |

**レスポンス:**
- 200: ユーザーオブジェクト
- 404: ユーザーが見つかりません

**例:**
[リクエストとレスポンス例]

---

3. コードコメントガイドライン

JSDoc/TSDoc テンプレート

/**
 * 関数の機能の簡潔な説明。
 * 
 * @param paramName - パラメータの説明
 * @returns 戻り値の説明
 * @throws ErrorType - このエラーが発生する条件
 * 
 * @example
 * const result = functionName(input);
 */

コメントを書く時機

✅ コメント	❌ コメント不要
なぜ（ビジネスロジック）	何（自明なこと）
複雑なアルゴリズム	全ての行
非自明な動作	自己説明的なコード
API契約	実装の詳細

---

4. Changelog テンプレート（Keep a Changelog）

# Changelog

## [Unreleased]
### Added
- 新機能

## [1.0.0] - 2025-01-01
### Added
- 初回リリース
### Changed
- 依存関係を更新
### Fixed
- バグ修正

---

5. アーキテクチャ決定記録（ADR）

# ADR-001: [タイトル]

## ステータス
Accepted / Deprecated / Superseded

## コンテキスト
なぜこの決定を行うのか？

## 決定
何を決定したのか？

## 結果
トレードオフは何か？

---

6. AI フレンドリー ドキュメンテーション（2025）

llms.txt テンプレート

AI クローラーとエージェント向け：

# Project Name
> 一行での目的説明。

## コアファイル
- [src/index.ts]: メインエントリー
- [src/api/]: API ルート
- [docs/]: ドキュメンテーション

## 主要概念
- 概念 1: 簡潔な説明
- 概念 2: 簡潔な説明

MCP 対応ドキュメンテーション

RAG インデックス向け：

• クリアな H1-H3 階層
• データ構造用の JSON/YAML 例
• フロー用の Mermaid ダイアグラム
• 独立したセクション

---

7. 構造の原則

原則	理由
スキャン可能	ヘッダー、リスト、表
例を最初に	説明だけでなく実例を示す
段階的な詳細化	シンプル → 複雑
最新の状態に保つ	古い情報は誤解を招く

---

覚えておいてください: テンプレートは出発点です。プロジェクトのニーズに合わせて適応させましょう。

いつ使用するか

このスキルは、概要に記載されたワークフローまたはアクションを実行する場合に適用できます。

制限事項

• このスキルは、上記で説明されたスコープと明確に一致するタスクの場合にのみ使用してください。
• 出力を、環境固有の検証、テスト、または専門家のレビューの代わりと見なさないでください。
• 必要な入力、権限、セキュリティ境界、または成功基準が不足している場合は、立ち止まって説明を求めてください。