gjkim-instruction

gjkim_instruction.md — Loop Engineering 的根文档

本文档的作用

Loop Engineering 会针对一个长期目标运行许多次短暂的 Agent 迭代。每次迭代开始时掌握的上下文都很少，因此需要一个稳定的位置，说明必须满足哪些条件，以及已经做出了哪些决定。这个位置就是 gjkim_instruction.md，存放在循环所处理项目的根目录中。

本文档要防范的失败模式是过早锁定决策。根文档中写下的任何内容，后续每次迭代都会将其视为要求并继承下来。如果写入了未经确认的细节——例如库的选择、架构，或仅仅是最初猜测的文件布局——错误的猜测就会永久保留下来，循环也会失去寻找更好答案的空间。因此，本文档只记录两类内容，并将其他所有内容都刻意留作开放项。

应写入的内容

• 目标：用一两句话说明这项工作必须实现什么。
• 最低要求：这项工作要取得成功必须满足的最少成果。描述成果，而非实现方式。
• 非目标：这项工作明确不追求的成果，以免迭代偏离方向。非目标是已确认的“我们不会做这件事”，而不只是尚未决定的事项——尚未决定的内容应放在“刻意留作开放项”下。
• 已确认的决策：仅记录用户明确确认过的决策。每条都附上确认日期和一句话说明原因，以便后续迭代判断该原因是否仍然适用。
• 刻意留作开放项（可选）：已知尚未决定的选项，列出这些选项，以免迭代默默假定某个答案。在此处列出某个选项并不代表认可它。

不应写入的内容

• 未经明确确认的实现细节：库、框架、架构、文件布局、API 形式、部署目标。
• 任务列表、进度日志、迭代状态。这些内容应放在 issue、PR 或迭代笔记中——根文档描述的是目的地，而非过程。
• 正在考虑的推测性设计或选项。最多只能在“刻意留作开放项”下提及，绝不能作为要求或决策。
• 任何可从代码本身推导出来的内容。

区分要求与细节的检验方法：是否有两种实质不同的实现都能满足它？如果只能用一种实现满足，那就是细节——在用户确认它为决策之前，不要写入。

模板

在项目根目录创建文档，并将其准确命名为 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>

如果没有值得提醒的内容，可省略“非目标”或“刻意留作开放项”部分。整份文档控制在一页左右；如果篇幅超过一页，就说明混入了过多细节——请删减。

维护文档

• 只有在用户明确确认后，才添加决策。“倾向于”“可能”或“也许”都不算确认。
• 只有在用户明确排除某个选项后，才记录为非目标。尚无人决定的选项应保留在“刻意留作开放项”下。
• 如果某次迭代必须做出文档中未记录的选择，请做出当前最合适的选择，在该迭代的 PR 或笔记中将其标记为未经确认，并提交给用户确认。此时不要将其写入根文档。
• 如果某项决策被推翻，请替换对应条目。文档只描述当前状态；旧状态由 git 历史保留。
• 更新时，除非用户明确修改，否则应保留现有要求和决策。