> 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/30-lightweight-ai-lifecycle.md).

# 30. 軽量AI開発ライフサイクル

## 目的

AIを活用した開発では実装速度が上がる一方で、古い仕様の復活、旧コードのコピー、チャットへの依存、仕様の散逸が起こりやすくなります。

リブログでは、重い開発プロセスを導入するのではなく、AIに正しい文脈を渡し、現在の仕様を保ちながら、小さく改善を続けるための軽量な開発ライフサイクルを採用します。AIは協調相手であり、仕様の採否、公開可否、最終的な判断は人間が行います。

## 基本サイクル

リブログのAI開発では、次の流れを基本とします。

1. 目的を決める
2. 現在仕様を確認する
3. 参考資料と正しい資産を分ける
4. 要件、設計、タスクを軽く整理する
5. Codexに変更範囲を明示して実装させる
6. 動作を確認する
7. 必要なテストを追加する
8. `current-spec.md`と`change-log.md`を更新する

変更が小さい場合は、必要な段階と文書だけを選びます。ただし、現在仕様、変更範囲、完了条件を確認しないまま実装や公開へ進めません。

## 基本思想

* AIは単なる実装者ではなく、協調相手として扱う
* 正しい仕様はチャットだけに残さず、リポジトリ内の文書へ反映する
* 古いソースや資料は、現在の正解ではなく参考資料として扱う
* まず動くものを作り、実際の利用を通じて改善する
* 正しいと判断した重要な振る舞いは、仕様やテストで固定する
* AIの出力、差分、動作、公開可否は人間が確認する

TDD/BDDを必須にするのではなく、必要な場面で使います。基本は、実装、動作確認、正しい振る舞いの仕様・テストへの固定という順で進めます。不具合の再現条件や期待結果が明確なロジックでは、先にテストを書く方法も選択できます。詳しい考え方は、[Codex開発の基本方針](/engineering-handbook/codexwoshitana/17-overview.md)と[テスト追加と動作確認](/engineering-handbook/codexwoshitana/23-testing.md)を参照してください。

GitHub Projectsの利用、一定のカバレッジ値、重いレビューゲートも一律の必須条件にはしません。既存の管理方法を尊重し、変更の規模とリスクに応じて必要な確認を選びます。

## Steering：プロジェクト共通ルール

Steeringは、CodexなどのAIに毎回共有したいプロジェクトの共通ルールです。特定のツール機能や厳密な承認手順ではなく、プロジェクトをまたいで変わりにくい前提をまとめる考え方として扱います。

必要に応じて、各プロジェクトに次のようなファイルを用意します。

| ファイル                | 役割                           |
| ------------------- | ---------------------------- |
| `product.md`        | プロダクトの目的、利用者、背景を整理する         |
| `tech.md`           | 技術構成、使用ライブラリ、実行環境を整理する       |
| `structure.md`      | ディレクトリ構成、命名規則、配置ルールを整理する     |
| `testing-policy.md` | テスト方針、確認観点、最低限の品質基準を整理する     |
| `ai-usage.md`       | Codexに依頼してよいこと、注意点、禁止事項を整理する |

すべてのプロジェクトで必ず作る必要はありません。既存の`README.md`や開発ガイドに同じ役割の情報があれば、それを利用します。ただし、継続的に育てるプロダクトでは、AIに読ませる前提の共通ルールを整備し、古い情報を放置しません。

共通ルールには毎回参照すべき情報だけを置き、機能固有の詳細はSpecへ分けます。機密情報や外部公開できない情報は記載しません。情報管理の基準は、[セキュリティとAI利用時の情報管理](/engineering-handbook/riburoguno/5-development-operations/security-and-ai-usage.md)を参照してください。

## Spec：機能単位の仕様整理

Codexに実装を依頼する場合、要件、設計、タスクが混ざっていると、AIが不足情報を推測して実装しやすくなります。そのため、ある程度の規模がある機能では、情報を機能単位で分けます。

```
docs/features/{feature-name}/
  requirements.md
  design.md
  tasks.md
  current-spec.md
  change-log.md
```

| ファイル              | 役割            |
| ----------------- | ------------- |
| `requirements.md` | 何を実現したいかを書く   |
| `design.md`       | どう実現するかを書く    |
| `tasks.md`        | 作業を小さく分解する    |
| `current-spec.md` | 現在の正しい仕様を書く   |
| `change-log.md`   | 仕様変更の履歴と理由を書く |

小さな修正ですべてを作る必要はありません。ただし、継続的に変更する機能では、修正後の正しい振る舞いを判断できるように、`current-spec.md`と`change-log.md`を優先して整備します。

詳細なテンプレートや更新方法は、[開発前に準備するファイル](/engineering-handbook/codexwoshitana/18-preparation-files.md)と[機能の継続更新](/engineering-handbook/codexwoshitana/29-continuous-feature-updates.md)を参照してください。既存プロジェクトに同じ役割の文書がある場合は、無理にファイル名を変更せず、どの文書が各役割を担うかを明確にします。

## Requirements / Design / Tasks の分離

AIに依頼する前に、「何を実現したいか」「どう実現するか」「何を作業するか」を分けて考えます。

### Requirements

Requirementsには、何を実現したいかを書きます。実装方法、クラス名、具体的なファイル配置は含めません。

```
ユーザーは都道府県を選択して、対象地点を絞り込める。
```

### Design

Designには、要件をどう実現するかを書きます。画面、API、DB、ファイル構成、データ形式、既存機能への影響などを整理します。

```
都道府県一覧は prefectures.json から読み込む。
検索条件はAPIのquery parameterとして送信する。
```

### Tasks

Tasksには、実際に何を作業するかを書きます。変更範囲と確認結果を追いやすい、Codexに渡せる単位まで分解します。

```
- 都道府県プルダウンを追加する
- 選択値を検索APIに渡す
- 検索結果を地図上に再描画する
- 動作確認手順をREADMEに追記する
```

この分離により、設計上の選択を要件と誤認したり、AIが不足する要件を勝手に補完したりするリスクを下げます。要件と設計の詳しい整理方法は、[要件整理と設計方針の作成](/engineering-handbook/codexwoshitana/21-requirements-and-design.md)を参照してください。

## Asset / Reference の分離

AI開発では、古いソースコードや設計書を渡すと、AIがそれを現在の正しい仕様として扱うことがあります。依頼時には、現在の判断根拠となるAssetと、意図を読み取るためのReferenceを明確に分けます。

| 区分        | 意味       | 例                                        |
| --------- | -------- | ---------------------------------------- |
| Asset     | 現在の正しい資産 | 現行ソース、`current-spec.md`、最新README、現在のDB定義 |
| Reference | 参考資料     | 旧ソース、旧設計書、過去メモ、古い仕様、移行元コード               |

Referenceは参考資料であり、正解ではありません。Asset同士が矛盾する場合もAIに優先順位を推測させず、人間が確認します。

CodexにReferenceを渡す場合は、次のように明示します。

```
以下は旧実装です。正解ではありません。
処理の意図を読み取り、現在の設計に合わせて再実装してください。
旧コードをそのままコピーしないでください。
不明点は推測せず、確認事項として報告してください。
```

## Re-modeling：旧仕様を新しい設計に再表現する

Re-modelingは、旧コードや旧仕様をそのまま移植するのではなく、業務ルールや本来の目的を抽出し、現在の設計に合わせて再表現することです。

悪い例は、旧システムのフラグ名と分岐を、意味を確認せずに残すことです。

```java
if (AGC_FLG == 1) {
    // 旧システムと同じ処理
}
```

良い例では、旧処理が表していた業務上の意味を確認し、現在のモデルの言葉へ置き換えます。

```
AGC設備を優先対象として扱う業務ルールがある。
現在のドメインモデルでは equipmentPriority として表現する。
```

AIに旧コードを渡す場合は、次を指示します。

* 旧コードをそのままコピーしない
* 変数名やフラグ名を意味の確認なしに採用しない
* 処理の意図と抽出したルールを説明する
* 現在のドメインモデルと設計に合わせて再設計する
* 不明点は推測せず、確認事項として列挙する

旧実装の挙動が現在も必要かどうかは、人間がAsset、利用状況、業務上の目的を基に判断します。

## AIに渡す情報の順番

Codexに実装を依頼するときは、いきなりソースコードだけを渡しません。基本的には、次の順番で情報を渡します。

1. 目的
2. 現在仕様
3. Requirements
4. Design
5. Tasks
6. 関連する現行ソース
7. Reference資料
8. 制約事項
9. 完了条件

小さな修正では項目を統合できますが、現在仕様、変更範囲、完了条件は省略しません。Reference資料はAssetの後に示し、正解ではないことを明示します。

悪い依頼：

```
この旧ソースを参考に新機能を作って。
```

良い依頼：

```
以下は旧ソースです。正解ではなくReferenceです。
処理の意図だけを読み取り、current-spec.mdと現在の設計に合わせて再実装してください。
旧コードをそのままコピーせず、不明点は確認事項として報告してください。
```

具体的な依頼項目とプロンプト例は、[Codex開発の基本方針](/engineering-handbook/codexwoshitana/17-overview.md)と[Codex依頼プロンプト集](/engineering-handbook/codexwoshitana/27-prompt-templates.md)を参照してください。

## 軽量な品質ゲート

リブログでは、重い承認フローよりも、公開前に最低限の確認を確実に行うことを重視します。可能な範囲で、次を確認します。

* ビルドが通る
* 主要画面が表示できる
* 主要APIが動作する
* 重要なロジックにテストがある
* READMEや`current-spec.md`が古くなっていない
* `change-log.md`に変更理由が残っている
* 文書、コード、ログ、生成物に機密情報が含まれていない
* APIキーやパスワードをコミットしていない
* 変更範囲に関係する既存機能を壊していない

すべての小修正に同じ確認量を求めるのではなく、影響範囲と失敗時の影響に応じて調整します。実行できなかった確認は成功扱いにせず、理由と未確認範囲を残します。テストの選び方は[テスト追加と動作確認](/engineering-handbook/codexwoshitana/23-testing.md)、公開情報の確認は[公開前チェックリスト](/engineering-handbook/handbooknoto/16-handbook-writing/publication-checklist.md)を参照してください。

## Hook：確認作業の自動化

Hookは、変更時や公開前に、開発者に代わって最低限の確認を行う仕組みです。特定のGit hookだけを指すのではなく、ローカルスクリプトやCIを含む自動チェックとして扱います。

必要に応じて、次を自動化します。

* Markdownリンクの確認
* READMEとSUMMARYの整合確認
* テスト実行
* ビルド確認
* formatとlint
* 機密情報の検出
* `.env`の誤コミット検出

Hookは開発を止めるためではなく、ミスを早く見つけるために使います。すべてを一度に導入せず、繰り返し起きるミスや、手動では漏れやすい確認から追加します。自動チェックに通ったことだけで公開可否を判断せず、人間が差分と動作を確認します。

## アンチパターン

### チャット駆動開発

チャットだけで仕様を決め、リポジトリ内の文書に残さない状態です。

問題：

* 後から仕様を追えない
* Codexに同じ前提を再現させにくい
* 別のAIや開発者へ引き継げない

対策：

* `current-spec.md`に現在仕様を残す
* `change-log.md`に変更理由を残す

### 旧ソースコピー開発

旧ソースをそのまま新しいシステムへ移植する状態です。

問題：

* 古い設計を引き継ぐ
* 不要なフラグや命名が残る
* 現在の設計と合わなくなる

対策：

* 旧ソースをReferenceとして扱う
* Re-modelingしてから実装する

### AI丸投げ開発

目的や制約を整理せず、AIに実装だけを依頼する状態です。

問題：

* AIが勝手に仕様を補完する
* 既存構成と合わない実装になる
* 差分の意図をレビューしにくくなる

対策：

* 目的、現在仕様、変更範囲、完了条件を明示する
* 不明点を推測せず報告させる

### Steering肥大化

共通ルールに機能固有の詳細や一時的な情報まですべて書く状態です。

問題：

* AIが重要な情報を見失う
* 文書がメンテナンスされなくなる
* 古いルールが残り続ける

対策：

* 共通ルールには毎回参照すべき情報だけを書く
* 詳細は各機能のSpecへ分ける
* 定期的に重複と古い記述を整理する

## 導入の目安

最初からすべてのファイルやHookを用意する必要はありません。小さな変更では、目的、現在仕様、変更範囲、完了条件を依頼に含め、動作確認と必要な文書更新を行うところから始めます。

継続的に変更する機能では`current-spec.md`と`change-log.md`を追加し、要件や設計が複雑になった段階でRequirements、Design、Tasksを分けます。同じ説明をAIへ繰り返している場合はSteeringへ移し、同じ確認漏れが起きる場合はHookへ移します。

運用の目的は文書や手順を増やすことではありません。AIが現在の仕様と変更範囲を理解でき、人間が小さな差分を確認しながら、安全に公開と改善を続けられる状態を作ることです。


---

# 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/30-lightweight-ai-lifecycle.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.