documentation-and-adrs

ドキュメントと ADR

概要

コードだけでなく、決定事項を文書化しましょう。最も価値のあるドキュメントは、決定に至った背景、制約、トレードオフといった「なぜ」を記録したものです。コードは「何を」構築したかを示しますが、ドキュメントは「なぜこの方法で構築したのか」と「どのような代替案を検討したのか」を説明します。この背景情報は、今後コードベースに携わる人やエージェントにとって不可欠です。

使用するタイミング

• 重要なアーキテクチャ上の決定を行うとき
• 競合するアプローチの中から選択するとき
• パブリック API を追加または変更するとき
• ユーザー向けの動作を変更する機能をリリースするとき
• 新しいチームメンバー（またはエージェント）をプロジェクトに迎えるとき
• 同じことを何度も説明していると気づいたとき

使用しない場合： 自明なコードは文書化しないでください。コードにすでに書かれていることを言い換えるコメントは追加しないでください。使い捨てのプロトタイプ向けにドキュメントを書かないでください。

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

ADR は、重要な技術的決定の背景にある理由を記録します。作成できるドキュメントの中で、最も価値の高いものです。

ADR を作成するタイミング

• フレームワーク、ライブラリ、または主要な依存関係を選ぶとき
• データモデルまたはデータベーススキーマを設計するとき
• 認証方式を選択するとき
• API アーキテクチャ（REST、GraphQL、tRPC など）を決定するとき
• ビルドツール、ホスティングプラットフォーム、またはインフラストラクチャを選ぶとき
• 後から変更するのにコストがかかる決定を行うとき

まず既存の規約に合わせる

ADR を作成する前に、既存の ADR、プロジェクトの指示、ADR 関連の設定やツール（例：.adr-dir ファイル）など、リポジトリ内の情報を調べ、確立された規約があるか確認してください。確立された規約がある場合は、以下のデフォルトよりもそちらを優先します。次の項目を既存の規約に合わせてください。

• 場所と形式 — 例：docs/adr/*.md、Documentation/Decisions/*.rst、MADR のレイアウト、または adr-tools の設定。既存のディレクトリ、ファイル拡張子、マークアップ（Markdown または reStructuredText）に合わせます。
• 番号付けと命名 — 既存の連番とファイル名のパターン（ADR-004-Title.rst、0004-title.md、…）を引き継ぎます。001 から始めたり、別の方式を新たに導入したりしないでください。
• セクション見出し — このテンプレートを押し付けず、プロジェクトで使われている見出しを再利用します。

既存の情報に矛盾がある場合は、別の方式を黙って導入するのではなく、その矛盾を明らかにしてください。規約が確認できない場合に限り、以下のデフォルトを適用してください。

ADR テンプレート

ADR は docs/decisions/ に連番で保存します（プロジェクトですでに別の場所を使用している場合を除きます。上記を参照してください）。

# ADR-001: Use PostgreSQL for primary database

## Status
Proposed | Accepted | Superseded by ADR-XXX | Deprecated

## Date
2025-01-15

## Context
We need a primary database for the task management application. Key requirements:
- Relational data model (users, tasks, teams with relationships)
- ACID transactions for task state changes
- Support for full-text search on task content
- Managed hosting available (for small team, limited ops capacity)

## Decision
Use PostgreSQL with Prisma ORM.

## Alternatives Considered

### MongoDB
- Pros: Flexible schema, easy to start with
- Cons: Our data is inherently relational; would need to manage relationships manually
- Rejected: Relational data in a document store leads to complex joins or data duplication

### SQLite
- Pros: Zero configuration, embedded, fast for reads
- Cons: Limited concurrent write support, no managed hosting for production
- Rejected: Not suitable for multi-user web application in production

### MySQL
- Pros: Mature, widely supported
- Cons: PostgreSQL has better JSON support, full-text search, and ecosystem tooling
- Rejected: PostgreSQL is the better fit for our feature requirements

## Consequences
- Prisma provides type-safe database access and migration management
- We can use PostgreSQL's full-text search instead of adding Elasticsearch
- Team needs PostgreSQL knowledge (standard skill, low risk)
- Hosting on managed service (Supabase, Neon, or RDS)

ADR のライフサイクル

PROPOSED → ACCEPTED → (SUPERSEDED or DEPRECATED)

• 古い ADR を削除しないでください。 過去の背景情報を記録しているためです。
• 決定が変わった場合は、古い ADR を参照して置き換える新しい ADR を作成してください。

インラインドキュメント

コメントを書くタイミング

「何を」ではなく「なぜ」をコメントに記載します。

// BAD: Restates the code
// Increment counter by 1
counter += 1;

// GOOD: Explains non-obvious intent
// Rate limit uses a sliding window — reset counter at window boundary,
// not on a fixed schedule, to prevent burst attacks at window edges
if (now - windowStart > WINDOW_SIZE_MS) {
  counter = 0;
  windowStart = now;
}

コメントを書かない場合

// Don't comment self-explanatory code
function calculateTotal(items: CartItem[]): number {
  return items.reduce((sum, item) => sum + item.price * item.quantity, 0);
}

// Don't leave TODO comments for things you should just do now
// TODO: add error handling  ← Just add it

// Don't leave commented-out code
// const oldImplementation = () => { ... }  ← Delete it, git has history

既知の注意点を文書化する

/**
 * IMPORTANT: This function must be called before the first render.
 * If called after hydration, it causes a flash of unstyled content
 * because the theme context isn't available during SSR.
 *
 * See ADR-003 for the full design rationale.
 */
export function initializeTheme(theme: Theme): void {
  // ...
}

API ドキュメント

パブリック API（REST、GraphQL、ライブラリインターフェース）については、次のようにします。

型と一緒に記述する（TypeScript では推奨）

/**
 * Creates a new task.
 *
 * @param input - Task creation data (title required, description optional)
 * @returns The created task with server-generated ID and timestamps
 * @throws {ValidationError} If title is empty or exceeds 200 characters
 * @throws {AuthenticationError} If the user is not authenticated
 *
 * @example
 * const task = await createTask({ title: 'Buy groceries' });
 * console.log(task.id); // "task_abc123"
 */
export async function createTask(input: CreateTaskInput): Promise<Task> {
  // ...
}

REST API には OpenAPI / Swagger を使用する

paths:
  /api/tasks:
    post:
      summary: Create a task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTaskInput'
      responses:
        '201':
          description: Task created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '422':
          description: Validation error

README の構成

すべてのプロジェクトに、次の項目を含む README を用意します。

# Project Name

One-paragraph description of what this project does.

## Quick Start
1. Clone the repo
2. Install dependencies: `npm install`
3. Set up environment: `cp .env.example .env`
4. Run the dev server: `npm run dev`

## Commands
| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server |
| `npm test` | Run tests |
| `npm run build` | Production build |
| `npm run lint` | Run linter |

## Architecture
Brief overview of the project structure and key design decisions.
Link to ADRs for details.

## Contributing
How to contribute, coding standards, PR process.

変更履歴の管理

リリースした機能については、次のようにします。

# Changelog

## [1.2.0] - 2025-01-20
### Added
- Task sharing: users can share tasks with team members (#123)
- Email notifications for task assignments (#124)

### Fixed
- Duplicate tasks appearing when rapidly clicking create button (#125)

### Changed
- Task list now loads 50 items per page (was 20) for better UX (#126)

エージェント向けドキュメント

AI エージェントのコンテキストについて、特に次の点を考慮します。

• CLAUDE.md / ルールファイル — エージェントが従うべきプロジェクトの規約を記載します
• 仕様ファイル — エージェントが適切なものを構築できるよう、仕様を最新の状態に保ちます
• ADR — 過去の決定に至った理由をエージェントが理解できるようにします（同じ決定をやり直すのを防ぎます）
• インラインの注意点 — エージェントが既知の落とし穴にはまるのを防ぎます

文章のレビュー

技術的な内容を確認した後、利用者にとって文章が適切かをレビューします。より明確な表現にしても、判断やその適用範囲を変えてはいけません。

1. 編集後も残すべき詳細（名前、数値と単位、コマンド、パス、リンク、条件、トレードオフ、不確実性）を確認します。利用可能なコードと判断の背景に照らし合わせ、裏付けを確認できないものには印を付けます。
2. ありきたりな導入、宣伝調の形容詞、繰り返しの要約を、読者が必要とする具体的な情報に置き換えます。根拠のない主張を、作り上げた例や、より強い保証に置き換えてはいけません。必要な技術的な繰り返しと、プロジェクトで定着している用語は維持します。
3. 編集後の文書を原文と情報源に照らし合わせます。失われた条件や注意事項を復元し、コマンドやコードの例が記載どおりに動作することを確認します。未解決の事実関係に関する疑問は、表現を整えるだけで済ませず、明記します。

よくある言い訳

言い訳	実際のところ
「コードを読めばわかる」	コードからわかるのは「何をするか」です。「なぜそうするのか」、どの代替案を退けたのか、どのような制約があるのかはわかりません。
「API が安定してからドキュメントを書く」	ドキュメントを書くことで、API の安定化は早まります。ドキュメントは設計の最初のテストです。
「ドキュメントを読む人はいない」	エージェントは読みます。将来のエンジニアも読みます。3 か月後の自分も読みます。
「ADR は余計な手間だ」	10 分かけて ADR を書けば、6 か月後に同じ判断をめぐって 2 時間議論せずに済みます。
「コメントは古くなる」	なぜそうするのか を説明するコメントは長く有効です。何をしているのか を説明するコメントは古くなります。だから前者だけを書きます。

注意すべき兆候

• 判断の根拠が文書化されていないアーキテクチャ上の決定
• ドキュメントも型もない公開 API
• プロジェクトの実行方法を説明していない README
• 削除せずにコメントアウトされたコード
• 何週間も残っている TODO コメント
• 重要なアーキテクチャ上の選択があるプロジェクトなのに ADR がない
• 意図を説明せず、コードを言い換えているだけのドキュメント

検証

ドキュメントを作成した後、次の点を確認します。

• 重要なアーキテクチャ上の決定すべてについて ADR がある
• README にクイックスタート、コマンド、アーキテクチャの概要が記載されている
• API 関数にパラメーターと戻り値の型のドキュメントがある
• 既知の注意点が、関係する箇所にインラインで記載されている
• コメントアウトされたコードが残っていない
• ルールファイル（CLAUDE.md など）が最新かつ正確である
• 文章の編集で、根拠のない保証を加えることなく、原文の詳細、判断のトレードオフ、条件が維持されている