gjkim-instruction

gjkim_instruction.md — ループエンジニアリングのルートドキュメント

このドキュメントが必要な理由

ループエンジニアリングでは、長期的な目標に対して、短いエージェントの反復を何度も実行します。各反復はコンテキストがほとんどない状態で始まるため、満たすべき要件と、すでに決定された内容を記す、安定した場所が必要です。その場所が、ループの作業対象となるプロジェクトのルートに置かれる gjkim_instruction.md です。

このドキュメントで防ぐべき失敗は、早い段階での決定の固定化です。ルートドキュメントに書かれた内容は、後続のすべての反復に要件として引き継がれます。未確認の詳細、たとえばライブラリの選択、スキーマ、最初の推測にすぎなかったファイル構成などを書き込むと、誤った推測が恒久化し、ループがより良い答えを見つける自由を失います。そのため、このドキュメントには2種類の内容だけを記録し、それ以外はすべて意図的に未確定のままにします。

記載する内容

• 目標：取り組みで達成すべきことを1、2文で記します。
• 最小要件：取り組みの成功に必須となる、最小限の成果を記します。実装レベルではなく、成果レベルで記載します。
• 対象外：取り組みで明示的に追求しない成果を記し、反復がその方向に逸れないようにします。対象外とは、「これは行わない」と確認済みの項目であり、単に未決定の項目ではありません。未決定の項目は「意図的に未確定」の下に記載します。
• 確認済みの決定事項：ユーザーが明示的に確認した決定事項のみを記します。後続の反復で理由が今も当てはまるか判断できるよう、各項目に確認日と理由を一行で添えます。
• 意図的に未確定（任意）：未決定だと分かっている選択肢を列挙し、反復で暗黙のうちに答えを仮定しないようにします。ここに選択肢を列挙しても、それを推奨することにはなりません。

記載しない内容

• 明示的に確認されていない実装の詳細：ライブラリ、フレームワーク、スキーマ、ファイル構成、API の形状、デプロイ先。
• タスクリスト、進捗ログ、反復の状況。それらはイシュー、PR、または反復メモに記載します。ルートドキュメントが記すのは目的地であり、そこに至る道のりではありません。
• 検討中の推測的な設計や選択肢。記載する場合も「意図的に未確定」の下に限り、要件や決定事項としては記載しません。
• コードそのものから導き出せる内容。

要件と詳細を見分ける判断基準：実質的に異なる2つの実装が、どちらもそれを満たせるでしょうか？実装が1つしか満たせないなら、それは詳細です。ユーザーが決定事項として確認するまで記載しないでください。

テンプレート

プロジェクトのルートに、名前を正確に gjkim_instruction.md としてドキュメントを作成します。

# <effort name>

Root document for loop engineering. Read this first in every iteration.
Anything not written here is an open choice.

## Goal

<one or two sentences>

## Minimum requirements

- <outcome that must hold>

## Non-goals

- <outcome explicitly not pursued>

## Confirmed decisions

- <decision> — confirmed <YYYY-MM-DD>. Why: <one line>

## Deliberately open

- <choice known to be undecided; do not assume an answer>

注意すべき内容がなければ、「対象外」または「意図的に未確定」のセクションは省略します。ドキュメント全体を1ページ程度に収めます。それ以上に長くなる場合は、詳細が入り込んでいるため、削ってください。

ドキュメントの管理

• 決定事項を追加するのは、ユーザーが明示的に確認した場合に限ります。「傾いている」「おそらく」「たぶん」は確認ではありません。
• 対象外を記録するのは、ユーザーが明示的に除外した場合に限ります。まだ誰も決定していない選択肢は、「意図的に未確定」の下に残します。
• 反復でドキュメントに記載されていない選択をする必要がある場合は、その場で最善の選択を行い、その反復の PR またはメモに未確認として記録したうえで、ユーザーに確認を提案します。まだルートドキュメントには記載しないでください。
• 決定が覆された場合は、その項目を置き換えます。ドキュメントに記載するのは現在の状態のみとし、以前の状態は git の履歴に残します。
• 更新時は、ユーザーが明示的に変更しない限り、既存の要件と決定事項を維持します。