# fix-document

> マージ前に spec/adr を更新する必要があるか確認し、ユーザーヒアリングしながら更新する。PRマージ前のドキュメント整合性チェックに使用。

- Author: Yoshimitsu.Kiyono
- Repository: kiyono/claude_code_development_template
- Version: 20260127145007
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/kiyono/claude_code_development_template
- Web: https://mule.run/skillshub/@@kiyono/claude_code_development_template~fix-document:20260127145007

---

---
name: fix-document
description: マージ前に spec/adr を更新する必要があるか確認し、ユーザーヒアリングしながら更新する。PRマージ前のドキュメント整合性チェックに使用。
---

# Fix Document Skill

マージ前にドキュメント（仕様書・ADR）の更新が必要かを確認し、必要に応じてユーザーヒアリングを行いながら更新するスキル。

## Overview

このスキルは以下の目的で使用する：

- PRマージ前のドキュメント整合性チェック
- コード変更に対応する仕様書の更新漏れ防止
- アーキテクチャ決定（ADR）の記録漏れ防止
- ドキュメントとコードの乖離防止

## Execution Strategy

### Phase 1: 変更内容の分析

1. **git diff の取得** - masterブランチとの差分を分析
2. **変更ファイルの分類** - 機能追加/変更/削除を特定
3. **影響範囲の特定** - どの機能・モジュールに影響があるか

### Phase 2: ドキュメント更新要否の判定

以下の基準で判定する：

| 変更種別 | 仕様書更新 | ADR更新 |
|----------|------------|---------|
| 新規機能追加 | 必要 | 場合による |
| API仕様変更 | 必要 | 不要 |
| データ構造変更 | 必要 | 場合による |
| アーキテクチャ変更 | 必要 | 必要 |
| バグ修正 | 不要 | 不要 |
| リファクタリング | 不要 | 場合による |
| 設定変更 | 場合による | 不要 |

### Phase 3: ユーザーヒアリング

更新が必要と判断した場合、AskUserQuestion ツールで以下を確認：

1. **変更の意図確認** - なぜこの変更を行ったか
2. **仕様の詳細確認** - 入出力、制約、エラーケース
3. **決定の背景確認**（ADR用） - 検討した選択肢、選定理由

### Phase 4: ドキュメント更新

1. **既存ドキュメントの確認** - docs/specs, docs/adrs を確認
2. **更新または新規作成** - ヒアリング内容を反映
3. **確認依頼** - ユーザーに内容確認を依頼

## Instructions

### Step 1: 変更差分の取得

```bash
# masterとの差分を取得
git diff master --name-status

# 変更内容の詳細を取得（コード変更）
git diff master -- "*.py"
```

### Step 2: 既存ドキュメントの確認

```bash
# 仕様書の確認
ls -la docs/specs/

# ADRの確認
ls -la docs/adrs/
```

### Step 3: 変更分析レポート作成

以下の形式で変更内容を整理：

```markdown
## 変更分析レポート

### 変更ファイル一覧
- [A] path/to/new_file.py - 新規追加
- [M] path/to/modified_file.py - 修正
- [D] path/to/deleted_file.py - 削除

### 機能的変更
1. [機能名]: [変更内容の要約]
2. ...

### ドキュメント更新要否判定

| 項目 | 判定 | 理由 |
|------|------|------|
| 仕様書（docs/specs） | 要/不要 | [理由] |
| ADR（docs/adrs） | 要/不要 | [理由] |
```

### Step 4: ユーザーヒアリング（必要な場合）

AskUserQuestion ツールで以下を確認：

#### 仕様書更新が必要な場合：

```
質問1: この変更で追加/変更された機能の概要を教えてください
質問2: 入出力データの形式や制約はありますか？
質問3: エラーケースや異常系の処理はどうなっていますか？
質問4: 既存の仕様書で更新すべき箇所はありますか？それとも新規作成ですか？
```

#### ADR更新が必要な場合：

```
質問1: この決定に至った背景・コンテキストを教えてください
質問2: 他に検討した選択肢はありましたか？
質問3: この選択肢を選んだ理由は何ですか？
質問4: この決定による影響やトレードオフはありますか？
```

### Step 5: ドキュメント更新

#### 仕様書の場合：

- 配置場所: `docs/specs/`
- ファイル名: `{機能名}_spec.md`
- 内容: docs/documents.md の仕様書セクションに従う

#### ADRの場合：

- 配置場所: `docs/adrs/`
- ファイル名: `adr-{3桁連番}-{kebab-case-title}.md`
- テンプレート: `docs/adrs/README.md` を参照
- 内容: docs/documents.md のADRセクションに従う

### Step 6: 完了レポート

```markdown
## ドキュメント更新レポート

### 更新内容

| ドキュメント | アクション | ファイル |
|--------------|------------|----------|
| 仕様書 | 新規作成/更新/不要 | docs/specs/xxx.md |
| ADR | 新規作成/更新/不要 | docs/adrs/adr-xxx-title.md |

### 更新したドキュメント

1. **docs/specs/xxx.md**
   - [更新内容の要約]

2. **docs/adrs/adr-xxx-title.md**
   - [更新内容の要約]

### 次のアクション

- [ ] ドキュメント内容の最終確認
- [ ] PRにドキュメント変更を含める
- [ ] レビュアーにドキュメント確認を依頼
```

## Usage Examples

### Example 1: 新機能追加後のドキュメントチェック

```
/fix-document
```

### Example 2: 特定の変更に対するドキュメントチェック

```
/fix-document 決済キャンセル機能の追加に関するドキュメント確認
```

## ADR テンプレート

| テンプレート | 用途 | ファイル |
|--------------|------|----------|
| **Nygard（推奨）** | シンプルな決定記録 | `assets/template-nygard.md` |
| **MADR** | 複数選択肢の比較が必要な場合 | `assets/template-madr.md` |

デフォルトは **Nygard テンプレート**（2011年に提案された最も標準的な形式）。

参考例: `references/example-nygard.md`

## ADR ファイル命名規則

```
docs/adrs/
├── adr-001-multi-vgw-architecture.md
├── adr-002-gateway-factory-pattern.md
├── adr-003-layered-architecture.md
└── README.md
```

形式: `adr-{3桁連番}-{kebab-case-title}.md`

## ADR ステータス種別

| ステータス | 説明 |
|------------|------|
| 提案中 | レビュー待ち |
| 承認済み | 合意済み、有効 |
| 却下 | 採用しないことを決定 |
| 非推奨 | 推奨されなくなった |
| 置き換え | 新しいADRで置き換えられた（例: 「置き換え by ADR-0005」） |

## 良いADRの特徴

- **1決定 = 1ADR**: 複数の決定を混ぜない
- **コンテキストは事実のみ**: 意見ではなく状況を記述
- **影響は正直に**: ネガティブな影響も隠さない
- **短く保つ**: 1-2ページが目安
- **不変**: 変更時は新しいADRを作成し、古いものは「置き換え」にする

## Notes

- **判断に迷う場合はユーザーに確認** - 自動判定で不確かな場合は必ず確認
- **既存ドキュメントとの整合性** - 新規作成より既存更新を優先
- **最小限の更新** - 変更に関連する部分のみ更新
- **docs/documents.md を参照** - ADR・仕様書の書き方はこのガイドラインに従う