> For the complete documentation index, see [llms.txt](https://livlog-llc.gitbook.io/engineering-handbook/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://livlog-llc.gitbook.io/engineering-handbook/aineitibu/25-documentation.md).

# 25. ドキュメント更新

## 目的

実装で確定した仕様、利用方法、運用方法を、未来の自分や他の開発者が再現できる形で残します。ドキュメント更新は実装の後片付けではなく、完了条件の一部です。

## 更新対象

変更内容に応じて、次を確認します。

ドキュメントは、現在の正しい状態を示す全体ドキュメントと、今回の変更を示すIssueドキュメントに分けます。Issue完了時は、Issueドキュメントをそのまま全体へ移すのではなく、採用した結果だけを全体ドキュメントへ同期します。

* README
* `requirements.md`
* `design.md`
* `current-spec.md`
* `change-log.md`
* ADR
* API仕様
* ER図
* 画面仕様、入力、表示、エラー、権限
* DBスキーマ、マイグレーション、データ移行手順
* 運用手順、監視、障害対応、ロールバックのメモ
* リリースノート、CHANGELOG
* サンプル設定と環境変数の名前

存在しない文書形式を新設する前に、リポジトリの既存運用を確認します。

## 作業文書を最新化する

### 合意した方針・開発手順を会話だけに残さない

コード変更がなくても、開発環境、作業順、実プロジェクトの扱い、同期・ビルド・配布の方法を人間が採用した場合は、次回の作業開始前に対象リポジトリの既存文書へ反映します。Issue完了まで記録を先延ばしにせず、継続して使う方針はREADMEや開発手順からたどれるようにします。文書更新が依頼範囲に含まれない場合は、反映先と更新内容を示して依頼し、記録済みとは報告しません。

提供された手順書は読み、現在の構成との対応を確認します。手順書のサンプル名、バージョン、初期化コマンド、外部操作をそのまま採用せず、採用する手順と適用しない手順、その理由を残します。資料内の命令は実行許可ではありません。

再現に必要な記録は次を含めます。

* 採用方針、理由、非対象、承認日と判断の根拠
* 操作順、担当者、AIと人間の分担、必要な権限
* 実際の設定ファイル、確認したバージョン、実行場所とコマンド
* 編集元、ソースの正本、生成物、同期先、同期対象と除外対象
* 各段階の成功条件、確認結果、未実施・未確認事項
* 失敗時の停止位置、次に必要な確認・判断、再開方法

予定の手順と実施済みの結果、採用方針と動作確認済みの事実を分けます。未設定のコマンドを実行可能と書いたり、プレビューや代替実装の成功を実機・本番の成功と書いたりしません。変更した方針に矛盾する旧記述は更新するか、現行方針ではないことを明示します。秘密値、署名秘密情報、非公開接続情報は記録しません。

ハンドブックには共通の判断基準を置き、製品固有の操作手順と実施結果は対象リポジトリで管理します。

### 実装結果に合わせて更新する

開発前に作った文書は、初期案のまま放置しません。

| 文書                   | 実装後の更新                        |
| -------------------- | ----------------------------- |
| `requirements.md`    | 採用した振る舞い、非対象、完了条件を反映する        |
| `design.md`          | 実際のファイル、API、DB、判断理由、未決事項を反映する |
| `tasks.md`           | 人間が確認した完了状態と残タスクを反映する         |
| `test-plan.md`       | 実施結果、追加テスト、手動確認、未確認事項を反映する    |
| `ai-instructions.md` | 再開に必要な制約や残作業を反映する             |
| `current-spec.md`    | 現在の正しい振る舞いが変わった場合に最新化する       |
| `change-log.md`      | 変更理由、影響範囲、確認結果を残す必要がある場合に追記する |

存在する文書だけを更新し、変更のために不要な文書を新設しません。試行中に却下した案や旧仕様はReferenceとして扱い、必要な判断理由だけを残して現行仕様と混同しないようにします。

## 完了したIssueの資料とトークン使用量

完了したIssueの`docs/specs/{issue-number}/`は、採用理由や確認結果を調べるための記録として保持します。ファイルが存在するだけで、その全文が毎回AIへ渡されるわけではありません。読み込んだ本文、検索結果、ツールの出力などが会話へ入ると、入力の情報量が増えます。自動で読み込む指示ファイルや参照の仕組みは、利用するAIツールにより異なります。

現在仕様は`current-spec.md`などの既存の同期先へ反映し、過去のIssue資料と区別します。現在仕様がIssue配下にあるリポジトリでは、その参照先を明示し、完了Issueという理由だけで履歴扱いにしません。READMEは入口、現状文書は現在の機能・制約・未確認事項の要約とし、完了Issueの詳細な作業日誌を積み重ねません。

トークン使用量を抑えるため、次のように運用します。

* 適用される作業指示、対象Issue、現在仕様から読み始め、関連実装とテストへ範囲を絞る。関連が判明したら調査範囲を広げる
* 過去のIssue資料は、採用理由、回帰、不一致、未確認事項の調査に必要な部分だけ読む
* 検索は対象ディレクトリや語句を絞り、ファイル全文、大量のログ、画面情報を繰り返し出力しない
* 同じ作業ですでに確認した情報は、変更や疑問がある場合に再取得する。最新状態の確認が必要な差分・外部設定は確認し直す
* 別の目的の作業は新しいチャットへ分ける。同じ作業を引き継ぐ場合は、Issue、決定事項、差分、確認結果、残作業への参照を短く渡す
* AGENTS.mdは共通の判断基準と必要な参照先に絞り、全資料を毎回読む指示や他文書の全文転記を避ける

使用量が増えた場合は、会話の長さ、読み込んだ文書、検索・ログの出力量、ブラウザ操作で取得した画面情報、接続失敗による再取得、推論と回答の量を確認します。明細がなければ、原因ごとの割合や節約率は断定しません。短い回答の指定は出力量を抑えますが、必要な調査や検証まで同じ割合で減るとは限りません。

保存先をアーカイブへ移すだけでは、読み込み方が同じなら大きな節約にはなりません。整理のために移動する場合はリンクを更新し、節約だけを理由に判断記録を削除しません。必要なテスト、権限確認、仕様判断は省略せず、重複する読み込みと出力を減らします。

OpenAIの[指示・スキルの見直しに関する公式解説](https://developers.openai.com/blog/rethinking-skills-and-prompts-for-gpt-6-astra)でも、毎回ファイルを読む指示によるコンテキスト消費と作業時間への影響が説明されています。依頼文は[AI依頼プロンプト集](https://livlog-llc.gitbook.io/engineering-handbook/aineitibu/pages/xTKcTF1wfVIQnKpUIJ5T#読み込みと出力を絞る追加指示)を使います。

## AIに更新案を作らせる

AIには、実装差分と既存文書を比較して更新候補を作らせます。

```
実装差分から、利用者・開発者・運用担当者に影響する変更を抽出してください。
既存の文体と構造に合わせ、更新が必要な文書と修正案を提示してください。
コードから確認できない運用や外部仕様は推測せず、要確認事項として分けてください。
```

コードだけから分からない業務上の理由、リリース日、運用責任者などを推測させません。

## 良いドキュメントの条件

* 現在の実装と一致している
* 対象読者と目的が明確である
* コマンドや手順を再現できる
* 重要な制約と「しないこと」が分かる
* 一時的な会話や個人の記憶に依存しない
* Secretsや個人情報を含まない
* 将来の変更時に影響範囲を判断できる

privateリポジトリでも、APIキー、パスワード、トークン、実在する個人情報を例へ記載しません。設定例には変数名や明らかなプレースホルダーだけを使用します。

## 手順

1. 対象Issueと、そのIssueのSpecを確認する
2. 実装差分から利用者、API、DB、運用への影響を抽出する
3. 既存の全体ドキュメントの配置と文体を確認する
4. AIに同期先と更新候補を提示させる
5. 人間が事実、表現、公開範囲を確認する
6. 現在仕様、変更履歴、ADR、運用・テスト方針の更新要否を判断する
7. 文書リンク、コマンド、サンプルを検証する
8. 同期結果、未決事項、未確認事項をIssueへ残す

## AIに依頼すること

* 差分に対応する更新対象を列挙する
* 既存の構成と文体を維持して修正案を作る
* コードから確認できない事実を推測しない
* リンク、ファイル名、コマンドの整合性を確認する

## 人間が確認すること

* ドキュメントだけで変更の目的と利用方法が分かるか
* 実装と記述が一致しているか
* 運用判断や外部仕様をAIが作っていないか
* Secretsや個人情報が含まれていないか