gjkim-instruction

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

gjkim_instruction.md — Root Document for Loop Engineering

gjkim_instruction.md — 循环工程根文档

Why this document exists

文档存在的意义

Loop engineering runs many short agent iterations against one long-lived goal. Each iteration starts with little context, so it needs one stable place that says what must be true and what has already been decided. That place is

gjkim_instruction.md

, kept at the root of the project the loop works on.

The failure mode this document guards against is early decision lock-in. Whatever is written in the root document, every later iteration inherits as if it were a requirement. If unconfirmed details get written down — a library choice, a schema, a file layout that was only a first guess — wrong guesses become permanent and the loop loses the freedom to find better answers. So the document records only two kinds of content, and treats everything else as deliberately open.

循环工程针对一个长期目标运行多次短周期Agent迭代。每次迭代开始时上下文信息很少，因此需要一个稳定的地方来明确必须满足的条件和已做出的决策。这个地方就是

gjkim_instruction.md

，保存在循环工程所针对的项目根目录下。

该文档旨在防范的失效模式是“早期决策锁定”。根文档中记录的任何内容，后续所有迭代都会将其视为要求继承。如果未确认的细节（如库选择、schema、仅为初步设想的文件布局）被写入文档，错误的猜测就会变成永久性限制，循环将失去寻找更优方案的自由。因此，该文档仅记录两类内容，其他所有内容均视为刻意保留的开放性事项。

What goes in

文档包含内容

Goal: one or two sentences on what the effort must achieve.
Minimum requirements: the smallest set of outcomes that must hold true for the effort to succeed. Outcome-level, not implementation-level.
Non-goals: outcomes the effort explicitly does not pursue, so iterations do not drift into them. A non-goal is a confirmed "we are not doing this", not merely something undecided — undecided things belong under "Deliberately open".
Confirmed decisions: only decisions the user has explicitly confirmed. Each entry carries the date it was confirmed and a one-line why, so a later iteration can tell whether the reason still applies.
Deliberately open (optional): choices that are known to be undecided, listed so iterations do not silently assume an answer. Listing an option here does not endorse it.

目标：用1-2句话说明该工作必须达成的成果。
最低要求：确保工作成功所需的最小成果集合。聚焦成果层面，而非实现层面。
非目标：明确不追求的成果，避免迭代偏离方向。非目标是已确认的“我们不会做这件事”，而非仅仅是未决定的事项——未决定的事项应归入“刻意保留的开放性事项”部分。
已确认决策：仅包含用户明确确认的决策。每条记录需标注确认日期和一行说明理由，以便后续迭代判断该理由是否仍然适用。
刻意保留的开放性事项（可选）：已知未决定的选项列表，用于避免迭代默认做出假设。在此列出选项并不代表认可该选项。

What stays out

文档排除内容

Implementation details that were not explicitly confirmed: libraries, frameworks, schemas, file layouts, API shapes, deployment targets.
Task lists, progress logs, iteration status. Those belong in issues, PRs, or iteration notes — the root document describes the destination, not the journey.
Speculative designs or options under consideration. Mentioning them at most under "Deliberately open", never as requirements or decisions.
Anything derivable from the code itself.

Litmus test for requirement vs. detail: could two meaningfully different implementations both satisfy it? If only one implementation can, it is a detail — leave it out until the user confirms it as a decision.

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

判断需求与细节的试金石：是否存在两种意义截然不同的实现方式都能满足它？如果只有一种实现方式能满足，那它就是细节——在用户将其确认为决策之前，请勿写入文档。

Template

模板

Create the document at the project root, named exactly

gjkim_instruction.md

markdown

undefined

在项目根目录创建该文档，文件名必须为

gjkim_instruction.md

：

markdown

undefined

<effort name>

<工作名称>

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

循环工程根文档。每次迭代前请先阅读本文档。未在此记录的所有内容均为开放性选择。

Goal

目标

<1-2句话>

Minimum requirements

最低要求

<outcome that must hold>

<必须达成的成果>

Non-goals

非目标

<outcome explicitly not pursued>

<明确不追求的成果>

Confirmed decisions

已确认决策

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

<决策内容> — 确认于<YYYY-MM-DD>。理由：<一行说明>

Deliberately open

刻意保留的开放性事项

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


Omit the "Non-goals" or "Deliberately open" section when there is nothing
useful to warn about. Keep the whole document around one page; if it grows
past that, details are leaking in — prune them.

<已知未决定的选项；请勿默认做出假设>


当没有需要提醒的内容时，可以省略“非目标”或“刻意保留的开放性事项”部分。保持整个文档篇幅在一页左右；如果篇幅超过一页，说明有细节混入——需进行删减。

Maintaining the document

文档维护

Add a decision only when the user has explicitly confirmed it. "Leaning toward", "probably", or "maybe" is not confirmation.
Record a non-goal only when the user has explicitly ruled it out. An option nobody has decided on yet stays under "Deliberately open".
When an iteration must make a choice that is not in the document, make the best local choice, record it in that iteration's PR or notes as unconfirmed, and propose it to the user for confirmation. Do not write it into the root document yet.
When a decision is reversed, replace the entry. The document describes only the current state; git history holds the old one.
When updating, preserve existing requirements and decisions unless the user explicitly changes them.

仅当用户明确确认后，才可添加决策。“倾向于”、“可能”或“也许”均不构成确认。
仅当用户明确排除某事项时，才可记录为非目标。尚未决定的选项应留在“刻意保留的开放性事项”部分。
当迭代必须做出文档中未提及的选择时，做出最佳的局部选择，在该迭代的PR或笔记中记录为未确认事项，并提交给用户确认。请勿立即写入根文档。
当决策被推翻时，替换对应的记录。文档仅描述当前状态；历史版本由git记录保存。
更新文档时，除非用户明确修改，否则保留现有的要求和决策。