documentation-templates

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

一般的なドキュメントの種類に対応するテンプレートと構成のガイドラインです。

---

1. README の構成

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

セクション	目的
タイトル＋一文の説明	これは何ですか？
クイックスタート	5 分以内に実行する
機能	何ができますか？
設定	カスタマイズ方法
API リファレンス	詳細なドキュメントへのリンク
コントリビューション	貢献方法
ライセンス	法的事項

README テンプレート

# Project Name

Brief one-line description.

## Quick Start

[Minimum steps to run]

## Features

- Feature 1
- Feature 2

## Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| PORT | Server port | 3000 |

## Documentation

- API Reference
- Architecture

## License

[Link to the actual project license; do not infer MIT]

---

2. API ドキュメントの構成

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

## GET /users/:id

Get a user by ID.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| id | string | Yes | User ID |

**Response:**
- 200: User object
- 404: User not found

**Example:**
[Request and response example]

---

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

JSDoc/TSDoc テンプレート

/**
 * Brief description of what the function does.
 * 
 * @param paramName - Description of parameter
 * @returns Description of return value
 * @throws ErrorType - When this error occurs
 * 
 * @example
 * const result = functionName(input);
 */

コメントを付ける場合

✅ コメントする	❌ コメントしない
理由（ビジネスロジック）	内容（自明な場合）
複雑なアルゴリズム	すべての行
一見して分からない動作	説明不要なコード
API の契約	実装の詳細

---

4. 変更履歴テンプレート（Keep a Changelog）

# Changelog

## [Unreleased]
### Added
- New feature

## [1.0.0] - 2025-01-01
### Added
- Initial release
### Changed
- Updated dependency
### Fixed
- Bug fix

---

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

# ADR-001: [Title]

## Status
Accepted / Deprecated / Superseded

## Context
Why are we making this decision?

## Decision
What did we decide?

## Consequences
What are the trade-offs?

---

6. AI に適したドキュメント（2025）

llms.txt テンプレート

AI クローラーとエージェント向け（example.com のリンクは構文を示す例です。実際に公開されているプロジェクトの URL に置き換えてください）：

# Project Name
> One-line objective.

## Core Files
- [Main entry](https://example.com/project/src/index.ts): Application entry
- [API routes](https://example.com/project/src/api/): Endpoint implementation
- [Documentation](https://example.com/project/docs/): User and contributor guides

## Key Concepts
- Concept 1: Brief explanation
- Concept 2: Brief explanation

MCP 対応ドキュメント

RAG インデックス作成向け：

• 明確な H1〜H3 の階層
• データ構造には JSON/YAML の例
• フローには Mermaid の図
• 自己完結したセクション

---

7. 構成の原則

原則	理由
一覧性	見出し、リスト、表
例を先に示す	説明だけでなく、実例を示す
段階的な詳細化	シンプルな内容から複雑な内容へ
最新の状態を保つ	古い情報は誤解を招きます

---

注意： テンプレートは出発点です。プロジェクトのニーズに合わせて調整してください。

使用する場合

実際のプロジェクトで README、エンドポイントリファレンス、変更履歴、ADR、またはエージェントが読み取れるインデックスが必要で、既存の規約に合わせた構成が必要な場合に使用します。

制限事項

• 例示用のパス、コマンド、日付、デフォルト値は、確認済みのプロジェクト情報に置き換えてください。テンプレートは、ワークフローが導入済みであることや、リンクや例が機能することを示すものではありません。
• 実際のライセンスと機密情報の範囲を守ってください。非公開のエンドポイントを公開したり、承認済みの ADR の決定事項を捏造したりしないでください。
• 上記の説明にある範囲とタスクが明確に一致する場合にのみ、このスキルを使用してください。
• 出力を、環境固有の検証、テスト、または専門家によるレビューの代わりとして扱わないでください。
• 必要な入力、権限、安全上の境界、または成功基準が不足している場合は、作業を止めて確認を求めてください。