# doc-edit

> 既存ドキュメントの更新・修正（仕様変更反映、情報追加など）

- Author: becky
- Repository: becky3/ai-assistant
- Version: 20260206175421
- Stars: 1
- Forks: 0
- Last Updated: 2026-02-06
- Source: https://github.com/becky3/ai-assistant
- Web: https://mule.run/skillshub/@@becky3/ai-assistant~doc-edit:20260206175421

---

---
name: doc-edit
description: 既存ドキュメントの更新・修正（仕様変更反映、情報追加など）
user-invocable: true
allowed-tools: Bash, Read, Edit, Write, Grep, Glob
argument-hint: "<file-path> [update-reason]"
---

## タスク

既存のプロジェクトドキュメントを安全に更新・修正する。ファイル構造を保持しながら必要な変更を加える。

## 引数

`$ARGUMENTS` の形式:
- `<file-path>`: 編集対象のファイルパス（必須）
- `[update-reason]`: 更新理由（オプション、指定がない場合は対話的に確認）

**例**:
```bash
/doc-edit docs/specs/f2-feed-collection.md
/doc-edit CLAUDE.md "スキル使用方法を追加"
```

## 処理手順

### 1. 引数解析とファイル確認

```bash
ARGS=($ARGUMENTS)
FILE_PATH="${ARGS[0]}"
UPDATE_REASON="${ARGS[@]:1}"  # 2つ目以降の引数を結合

# ファイル存在確認
if [ ! -f "$FILE_PATH" ]; then
  echo "エラー: ファイル $FILE_PATH が見つかりません"
  exit 1
fi
```

### 2. 現在の内容を読み込み

- Readツールでファイル全体を読み込む
- ドキュメントの構造（セクション、見出し、フォーマット）を理解する
- ドキュメントの種類を判定（仕様書/レトロ/CLAUDE.md等）

### 3. 更新理由の確認

**更新理由が指定されている場合**:
- 指定された理由に基づいて更新箇所を特定

**更新理由が指定されていない場合**:
- 最近のコミット・PR・Issueを調査し、更新が必要な箇所を推測
- または、対話的に「どの部分を更新しますか？」と確認

### 4. 関連情報の調査（必要に応じて）

**仕様書の場合**:
```bash
# 関連するコード変更を確認
git log --oneline --grep="f{N}" -10

# 関連PR
gh pr list --search "in:title <feature-name>" --state all
```

**CLAUDE.mdの場合**:
- 変更が開発ルール・プロジェクト構造に影響しないか確認

### 5. ドキュメントの更新

- **構造を保持**: 既存のセクション構成を壊さない
- **一貫性を保持**: 既存の書式・スタイルに従う
- **必要最小限の変更**: 更新箇所以外は変更しない

**編集方法**:
- 小規模な変更: Editツールで該当箇所のみ置換
- 大規模な変更: Writeツールでファイル全体を書き直す（構造を保持）

### 6. 変更内容の表示

```bash
# 変更前後のdiffを表示
git diff --no-index /dev/null $FILE_PATH 2>/dev/null || git diff $FILE_PATH
```

### 7. 更新結果のサマリー

```
✓ ドキュメントを更新しました: {file-path}

変更内容:
- [変更箇所1の説明]
- [変更箇所2の説明]

更新理由: {update-reason}
```

## ドキュメント種別ごとの更新パターン

### A. 仕様書 (`docs/specs/*.md`)

**よくある更新**:
- 受け入れ条件 (AC) の追加・修正
- 技術仕様の詳細化
- 関連ファイルの追加
- テスト方針の更新

**注意点**:
- ACの番号を変更しない（既存のテストコードと紐づいている）
- 新しいACは末尾に追加

### B. レトロスペクティブ (`docs/retro/*.md`)

**よくある更新**:
- 「改善点」セクションへの追記
- 「次に活かすこと」の具体化

**注意点**:
- 実装完了後の振り返りなので、基本的には追記のみ

### C. CLAUDE.md

**よくある更新**:
- 新しいスキルの使用方法追加
- 開発ルールの追加・修正
- プロジェクト構造の更新

**注意点**:
- 既存のルールを削除する場合は慎重に（他のドキュメントに影響する可能性）
- セクション構造を保持

## エラーハンドリング

- ファイルが存在しない場合:
  ```
  エラー: ファイル {file-path} が見つかりません。
  新規作成する場合は `/doc-gen` を使用してください。
  ```

- 引数が不正な場合:
  ```
  エラー: ファイルパスが指定されていません。
  使用方法: /doc-edit <file-path> [update-reason]
  ```

- 読み取り専用ファイルの場合:
  ```
  警告: {file-path} は読み取り専用です。
  編集しますか？ (y/n)
  ```

## 安全性の担保

1. **必ず既存内容を読み込む**: Editツール使用前にReadで内容を確認
2. **構造を保持**: セクション見出し、リスト形式、テーブル等を壊さない
3. **差分を表示**: 変更前後の差分を必ず表示してユーザーに確認
4. **バックアップ不要**: Gitで管理されているため、問題があれば `git restore` で復元可能

## 出力例

```
✓ ドキュメントを更新しました: docs/specs/f2-feed-collection.md

変更内容:
- AC7を追加: エラー発生時のリトライ処理
- 関連ファイルにretry_handler.pyを追加
- テスト方針にリトライのテストケースを追記

更新理由: Issue #45でリトライ機能が追加されたため

git diff:
+- [ ] AC7: エラー発生時に3回までリトライする
+| `src/services/retry_handler.py` | リトライロジック |
```

## 注意事項

- 更新後は必ず内容をレビューし、意図しない変更がないか確認する
- 大規模な構造変更が必要な場合は、新規ドキュメントを作成する方が安全
- CLAUDE.mdの変更は他のドキュメントに影響する可能性があるため特に慎重に