> 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/codexwoshitana/25-documentation.md).

# 25. ドキュメント更新

## 目的

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

## 更新対象

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

* READMEのセットアップ、実行、設定、利用方法
* `docs`配下の要件、設計、タスク、テスト計画
* OpenAPIなどのAPI仕様
* 画面仕様、入力、表示、エラー、権限
* DBスキーマ、マイグレーション、データ移行手順
* 運用、監視、障害対応、ロールバックのメモ
* CHANGELOGやリリースノート
* サンプル設定と環境変数の名前

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

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

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

| 文書                      | 実装後の更新                        |
| ----------------------- | ----------------------------- |
| `requirements.md`       | 採用した振る舞い、非対象、完了条件を反映する        |
| `design.md`             | 実際のファイル、API、DB、判断理由、未決事項を反映する |
| `tasks.md`              | 人間が確認した完了状態と残タスクを反映する         |
| `test-plan.md`          | 実施結果、追加テスト、手動確認、未確認事項を反映する    |
| `codex-instructions.md` | 再開に必要な制約や残作業を反映する             |

試行中に却下した案は、必要な判断理由だけを残し、現行仕様と混同しないようにします。

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

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

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

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

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

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

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

## 手順

1. 実装差分から利用者、API、DB、運用への影響を抽出する
2. 既存の文書配置と文体を確認する
3. Codexに更新候補を提示させる
4. 人間が事実、表現、公開範囲を確認する
5. 要件、設計、タスク、テスト計画を最新化する
6. 文書リンク、コマンド、サンプルを検証する
7. 未決事項と未確認事項を残す

## Codexに依頼すること

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

## 人間が確認すること

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://livlog-llc.gitbook.io/engineering-handbook/codexwoshitana/25-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.