Back to Details

archie-scope

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Scope

范围

One Epic, one session. Reach shared understanding of what it covers by interviewing, record the durable decisions as they settle, and end on a recommendation: split this Epic into children, or specify it. The Epic's own file is written once, at that recommendation, and the call is the user's.
Read 
references/epic-tree.md
 first. It fixes the tree on disk, how an Epic's state is read off its own files, identity numbering and the reference syntax.
Requires 
/archie-interview
for the questioning and 
/archie-domain-modeling
for anything durable, and it dispatches 
/archie-research
. Each carries its own discipline and knows nothing about Epics, altitude or this tree, so everything framework-shaped below is yours. If one is not installed, say which and stop rather than improvising it — a session that asks its questions unbounded, or leaves a decision nobody writes down, produces a tree that reads finished and is not.
You settle the what. How it gets built is 
/archie-design
's, on a leaf, after its Spec exists, and you never write 
spec.md
or a task file.
单个Epic对应一次会话。通过访谈达成对Epic覆盖内容的共识，记录最终确定的持久化决策，并给出最终建议：将该Epic拆分为子Epic，或明确其需求（制定Spec）。Epic自身的文件会根据建议一次性生成，最终决定权在用户手中。
请先阅读
references/epic-tree.md
。该文件定义了磁盘上的Epic树结构、如何从文件读取Epic状态、编号规则及引用语法。
依赖：提问环节需要
/archie-interview
，持久化记录需要
/archie-domain-modeling
，同时会调用
/archie-research
。每个工具都有其专属职责，且不了解Epic、高层面规划或Epic树的相关逻辑，因此以下所有框架性内容均由你负责。若某工具未安装，请明确指出并终止流程，切勿自行变通——无边界提问或未记录决策的会话，会导致生成的Epic树看似完整实则无效。
你负责确定内容范围。具体实现方式属于
/archie-design
的职责，需在叶子节点的Spec生成后开展，你无需编写
spec.md
或任务文件。

1. Open the Epic

1. 打开Epic

Nothing about this Epic is written to disk until step 4. The intent is agreed at the moment of least knowledge and the interview reshapes it, so writing it now buys a file that gets rewritten and a directory left behind by a session the user abandons. Hold it in the session instead.
A loose idea — no reference, just a subject. Agree a title and a slug. This is the root Epic and carries no number, and its 
epic.md
will look like this when step 4 writes it:
md
undefined
在步骤4之前，不要将该Epic的任何内容写入磁盘。因为初始意图是在信息最少时达成的，访谈会重塑这一意图，若现在写入文件，后续可能需要重写，且用户放弃会话时会留下无用目录。请在会话中暂存相关内容。
模糊想法——无引用，仅为一个主题。商定标题和短标识（slug）。这是根Epic，无编号，步骤4写入时其
epic.md
格式如下：
md
undefined

{Title}

{Title}

{One or two sentences of intent: what this Epic covers, in the project's language.}
{一到两句意图描述：用项目专属语言说明该Epic的覆盖范围。}

Decisions

Decisions

  • {One at-altitude decision settled at this resolution, in one line.}
  • {本次高层面规划确定的一项决策，单行表述。}

Children

Children

  1. 01-{slug}
    — {one line of intent}
  2. 02-{slug}
    — {one line of intent}

`## Decisions` is **always written**, because its presence is what marks this Epic as scoped: with no residue it carries the single line `_None at this resolution._`. `Children` is the **build order** authority and appears only on a Split Epic. A Specified Epic has no `Children`, and its `spec.md` and `tasks/` sit beside this file.

**An Epic reference** (`3.2`, or a root's slug) — resolve it down the numbered directories and open that Epic. A reference that does not resolve, or an Epic holding both children and a `spec.md`, stops the session and goes to the user.

An Epic that is already **Split** is not the one to scope: name its children's states and ask which to open. An Epic that already carries a `spec.md` has had its session; re-running here means **re-scoping**, which is step 6.

Done when a loose idea has an agreed title, slug and intent, or a referenced Epic is open and thin — and nothing new has been written either way.
  1. 01-{slug}
    — {一行意图描述}
  2. 02-{slug}
    — {一行意图描述}

`## Decisions`**必须写入**，因为它是标记该Epic已完成范围定义的标识：若无决策记录，需写入单行内容`_None at this resolution._`。`Children`是**构建顺序**的权威依据，仅在拆分后的Epic中存在。已明确需求的Epic无`Children`节点，其`spec.md`和`tasks/`目录与`epic.md`同级。

**Epic引用**（如`3.2`或根Epic的slug）——通过编号目录解析并打开对应Epic。若引用无法解析，或Epic同时包含子节点和`spec.md`，则终止会话并交由用户处理。

已**拆分**的Epic无需进行范围定义：说明其子节点的状态并询问需打开哪个节点。已包含`spec.md`的Epic已完成范围定义会话；再次执行此流程意味着**重新定义范围**，对应步骤6。

完成标志：模糊想法已商定标题、短标识和意图，或引用的Epic已打开且内容简洁——且未写入任何新内容。

2. Inherit before asking anything

2. 先继承约束，再开展提问

An Epic deep in a tree has most of its constraints already settled, in two places. Assemble both before opening your mouth, so the interview neither re-litigates a decision nor plans against a state it could have read.
位于树结构深层的Epic，其大部分约束已在两处确定。在提问前先整合这些约束，避免访谈重复讨论已决策内容，或与已读取的状态相悖。

What was written down

已记录的内容

  • CONTEXT.md
     — the project's language. Ask in it.
  • The ADRs touching this area — read the titles, then the bodies of the ones that bear on this subject. A question an ADR already answers is not a question.
  • Every ancestor's 
    epic.md
    , walking the path from the root down to this Epic's parent. Those 
    Decisions
    lines are inherited, not copied: they stay where they were written, because copying them onto children would contradict thin children and would need backfilling every time an ancestor settles something after the split. A decision spanning siblings is settled at the parent, so no sibling inherits one it never weighed in on.
  • CONTEXT.md
    ——项目专属语言。需基于此文件提问。
  • 与该领域相关的ADR——先阅读标题，再阅读与主题相关的ADR正文。ADR已解答的问题无需再提问。
  • 所有祖先节点的
    epic.md
    ——从根节点遍历至该Epic的父节点。这些
    Decisions
    行是继承而非复制：它们保留在原写入位置，因为复制到子节点会违背细粒度子Epic的设计，且祖先节点后续确定的决策需要回填到所有子节点。跨子节点的决策需在父节点确定，避免子节点继承未参与讨论的决策。

What was built

已构建的内容

A thin child is a deliberate deferral to a moment of strictly greater knowledge, and this is where that knowledge gets collected. The siblings ahead of this Epic in the parent's ordered child list are built: their code is on disk, and it is the current state of the thing being sharpened.
Their 
spec.md
and their Tasks name what they produced; the code is the authority on what it actually became. Look for the shape the interview has to fit inside: the seams that exist, the models and their names, the patterns already chosen, and the places where the built code diverged from what its Spec said.
Skip this only at a root Epic with nothing built.
Done when you can state, in a few lines, what this Epic has inherited and which of its own questions are already answered.
细粒度子Epic是刻意将决策推迟至信息更充分的时刻，而此处正是收集这些信息的地方。父节点有序子列表中排在该Epic之前的子节点已完成构建：其代码已存储在磁盘上，是当前系统的最新状态。
这些子节点的
spec.md
和任务文件定义了预期产出；代码则是实际产出的权威依据。需找出访谈必须适配的现有结构：已存在的模块边界、模型及其名称、已选择的模式，以及实际代码与Spec的差异。
仅当根Epic无已构建内容时可跳过此步骤。
完成标志：能用几句话说明该Epic继承的约束，以及哪些问题已得到解答。

3. Interview

3. 访谈

Invoke 
/archie-interview
for the questioning discipline — one question a turn, each carrying a recommended answer. It interviews about whatever it is pointed at; the bounding is yours.
调用
/archie-interview
执行提问流程——每次提出一个问题，并给出推荐答案。该工具可针对指定对象开展访谈，范围界定由你负责。

The frontier

待解决问题集

The frontier is the set of at-altitude questions still open on this Epic. It is the session's whole state, and the session ends when it is empty.
Fill it before asking anything: name every question this Epic raises — from the intent, the inherited decisions, and the code the earlier siblings produced — and put each one through the gate below. Answers open new questions, so the frontier keeps refilling; every newcomer takes the gate before it joins. Done when no question you can currently name is unsorted: each is on the frontier or has been announced as deferred.
待解决问题集是该Epic尚未解决的高层面问题集合。它是会话的核心状态，会话会在问题集为空时终止。
提问前先填充问题集：列出该Epic引发的所有问题——来自意图、继承的决策及早期子节点的代码——并逐一通过以下筛选机制。答案会引出新问题，因此问题集需持续补充；每个新问题加入前都需通过筛选。完成标志：所有当前可想到的问题均已分类，要么纳入待解决问题集，要么已宣布推迟解决。

The gate

筛选机制

Does this answer's blast radius reach beyond one part of this Epic?
At altitude means the blast radius does reach past one part: settle it here, now. Below altitude means it lives inside one part, so it is deferred to the moment that part is worked on — a bet on strictly greater knowledge later, since by then that part's earlier siblings are built and their code is there to read.
The gate is enforced, not advisory. A question that fails it is deferred the moment it occurs to you, never asked because the conversation happened to be nearby. Asking below altitude is how a session about a whole application ends up specifying one screen's layout, which is the waterfall Archie exists to replace. Sessions terminate on their own because cross-cutting decisions at any resolution are few, while local ones are many.
A how-question is not yours either. Which endpoints exist, which components get built, which package gets added, where the tests attach — those are 
/archie-design
's, one rung down, on a leaf whose Spec exists. Say so and move on:
md
_Design:_ what the reset endpoint's shape is.
That is not a deferral into a child, so it never joins a cluster. It is the same Epic, a later step.
Announce each real deferral in one line, in the turn it happens, so the user watches the child list assemble:
md
_Deferred:_ how the reset email is templated.
The user overrules the gate continuously. When they name a deferred question, it returns to the frontier and gets asked next, with no argument and no re-litigating the altitude.
该问题的影响范围是否超出该Epic的某一部分？
高层面意味着影响范围超出某一部分：需立即在此处解决。非高层面意味着影响范围局限于某一部分，因此需推迟至该部分开始开发时解决——这是对未来信息更充分的一种预判，届时该部分的前置子节点已完成构建，可参考其代码。
**筛选机制是强制执行的，而非建议性的。**未通过筛选的问题需立即推迟解决，即便当前话题相关也不得提问。提问非高层面问题会导致原本针对整个应用的会话最终聚焦于单个页面的布局，而这正是Archie要取代的瀑布式开发模式。会话会自行终止，因为任何层面的跨域决策数量有限，而局部决策数量众多。
实现类问题也不属于你的职责范围。哪些端点存在、构建哪些组件、添加哪个包、测试附着位置——这些均属于
/archie-design
的职责，需在叶子节点的Spec生成后开展。需明确说明并继续推进：
md
_设计阶段:_ 重置端点的结构。
这并非推迟至子节点，而是同一Epic的后续步骤。
每次推迟决策时需用单行内容宣布，以便用户实时查看子节点列表的形成：
md
_推迟解决:_ 重置邮件的模板方式。
用户可随时推翻筛选机制。当用户提及已推迟的问题时，需将其重新纳入待解决问题集并优先提问，无需争论或重新讨论层面界定。

Record what settles, the moment it settles

实时记录已确定的内容

The durable levels are written now, before the next question is asked. Invoke 
/archie-domain-modeling
for a domain term or a decision clearing the ADR bar; it owns those two destinations and knows nothing about this tree. Those are the levels that outlive the tree, so a session that dies before step 4 must not take them with it.
The residue is held in the session and written in step 4: one line per decision, no reasoning, the list you will put under 
## Decisions
. Keep it as you go rather than reconstructing it at the end, restate it in every check-in, and revise a line in place when a later answer sharpens it. The residue is the level defined to die with the tree, so holding it costs the same class of loss a pivot already costs.
If a residue line will not fit in one line, it needed its reasoning — which means it was an ADR, and it goes to 
/archie-domain-modeling
now. That test is what keeps 
epic.md
from growing into a spec.
持久化内容需立即写入，在提出下一个问题前完成。调用
/archie-domain-modeling
处理领域术语或符合ADR标准的决策；该工具负责这两类内容的存储，且不了解Epic树的相关逻辑。这些内容会长期留存，因此会话若在步骤4前中断，不得丢失此类内容。
临时记录需暂存在会话中，并在步骤4写入：每条决策单行表述，无需推理，最终会放入
## Decisions
下。需实时记录而非事后重构，每次同步时重申内容，后续答案完善时需及时修改对应行。临时记录是随Epic树更新而淘汰的内容，因此暂存的损失与项目转型的损失相当。
若临时记录无法单行表述，则需要补充推理——这意味着它属于ADR，需立即交由
/archie-domain-modeling
处理。这一规则可避免
epic.md
演变为Spec文件。

A hard question is not a low one

复杂问题无需低层面处理

An at-altitude question about a fact — something the user would have to go and read — takes the research exit rather than the user's attention. It runs in a sub-agent and comes back as a pointer, so the reading never enters this session's context.
Spawn the sub-agent and tell it to use 
/archie-research
; the skill is the sub-agent's, and what only you know is the brief: the question in one sentence, what decision is waiting on it, and the destination — 
research/<slug>.md
inside this Epic's own directory. One answerable question per sub-agent, since a brief asking three things comes back as three shallow answers.
Carry on down the frontier while it runs, and ask the waiting question when its pointer lands.
That destination is the one thing that reaches disk before step 4, so create the directory lazily — the first finding brings it into existence, and nothing else goes in it. An Epic carrying only 
research/
is still thin.
关于事实的高层面问题——用户需要查阅资料才能回答的问题——需走研究流程，而非占用用户注意力。它会在子Agent中运行，并返回一个指向资料的链接，因此查阅过程不会进入本次会话的上下文。
生成子Agent并告知其使用
/archie-research
；该工具由子Agent负责，你只需提供简要说明：用一句话表述问题、等待该问题答案的决策、以及存储路径——该Epic目录下的
research/<slug>.md
。每个子Agent仅处理一个可回答的问题，因为包含三个问题的简要说明会返回三个浅层答案。
在子Agent运行期间继续处理待解决问题集，收到链接后再提出等待的问题。
该存储路径是步骤4前唯一可写入磁盘的内容，因此需延迟创建目录——首次研究结果生成时再创建目录，且目录中不得存放其他内容。仅包含
research/
目录的Epic仍属于细粒度Epic。

Check in every eight questions

每八个问题同步一次

Roughly every eighth question, open the turn with three lines, then ask the next question in the same turn. The check-in is a backstop against your own altitude judgement being wrong, not a decision point, so it never stops for approval:
md
**Check-in.** Settled: reset is token-based, tokens expire in an hour, all sessions drop.
Deferred: 6, clustering into email delivery and the reset UI.
Leaning: split.
The lean is either split or specify, read off the deferrals as they stand: several clusters lean split, a thin scattering of deferrals leans specify.
Done when the frontier is empty. What it leaves behind is either nothing — every question at this resolution settled — or the deferrals, which cluster in step 4.
大约每提出八个问题后，需在本轮开始时先列出三行内容，再提出下一个问题。同步是为了避免你的层面判断出错，并非决策环节，因此无需等待批准：
md
**同步。**已确定：重置基于令牌，令牌1小时过期，所有会话终止。
推迟解决：6项，归类为邮件发送和重置UI两类。
倾向建议：拆分。
倾向建议为拆分或明确需求，基于当前推迟解决的问题判断：多个聚类倾向于拆分，少量分散的推迟问题倾向于明确需求。
完成标志：待解决问题集为空。最终结果要么是无任何遗留——该层面的所有问题均已解决；要么是存在推迟解决的问题，需在步骤4中聚类。

4. Write the Epic, then recommend

4. 写入Epic文件并给出建议

The frontier is empty, so what the Epic is has stopped moving. Write it now, in one go: create 
.archie/<path>/
if the research exit did not, and write 
epic.md
with the title, the intent as the session actually came to understand it, and 
## Decisions
carrying the residue — or 
_None at this resolution._
if there is none.
An Epic that already had an 
epic.md
is updated in the same single write: the intent sharpened if this session sharpened it, 
## Decisions
extended with this session's residue. Its existing lines were settled at this resolution too and are not rewritten away.
That write and the recommendation land in the same turn, so the recommendation is the diff — the user reads what was settled and what you propose doing about it together, rather than approving a recommendation about files that already changed under them.
The children are proposed here and written in step 5, because which children exist is still the user's call.
Then cluster the deferrals — each cluster named, with the deferred questions under it — and read the recommendation off them, giving the reasoning with it:
  • An empty frontier and no deferrals — recommend specify. Everything at this resolution is settled and there is nothing left to sharpen.
  • Deferrals in clusters — recommend split, one child per cluster, in the build order you would suggest, with a line on why each is a child rather than a question you should have asked.
Present it as a recommendation and stop. Going deeper is the user's call, always — they may specify an Epic you wanted to split, split one you wanted to specify, merge two of your clusters or add a child you missed. Do that, do not argue it twice.
On specify, name 
/archie-to-spec
as the next step and stop. Nothing else here writes a Spec.
待解决问题集为空，Epic的范围已确定。现在一次性写入内容：若研究流程未创建
.archie/<path>/
目录则创建，然后写入
epic.md
，包含标题、会话最终达成的意图描述，以及
## Decisions
部分的临时记录——若无记录则写入
_None at this resolution._
。
若Epic已有
epic.md
文件，则以同样方式更新：若会话完善了意图则更新意图描述，
## Decisions
部分补充本次会话的临时记录。原有记录是该层面已确定的决策，不得覆盖。
文件写入与建议需同步完成，因此建议就是变更内容——用户可查看已确定的内容及你提出的后续方案，而非在文件已变更的情况下批准建议。
子节点在此处提出建议，在步骤5中写入，因为子节点的最终决定权在用户手中。
随后将推迟解决的问题聚类——每个聚类命名，并列出对应的推迟问题——基于聚类结果给出建议并说明理由：
  • 待解决问题集为空且无推迟问题——建议明确需求。该层面的所有问题均已解决，无需进一步细化。
  • 推迟问题已聚类——建议拆分，每个聚类对应一个子Epic，按你建议的构建顺序排列，并说明每个子Epic的合理性（为何不作为你本应提出的问题）。
将内容作为建议呈现后终止流程。深入推进始终由用户决定——他们可能选择明确你建议拆分的Epic，拆分你建议明确的Epic，合并你提出的聚类或添加你遗漏的子节点。执行用户的选择，无需二次争论。
若建议为明确需求，需指定
/archie-to-spec
作为下一步并终止流程。此处无需编写Spec。

5. Split, if that is the call

5. 若选择拆分则执行拆分

A child is created thin: a directory 
NN-<slug>
taking the next unused number, an 
epic.md
holding the title and one or two lines of intent and no 
## Decisions
heading, and a line in the parent's ordered 
Children
list — which is where the parent's 
epic.md
, written a step ago without one, gains its 
Children
section. Nothing else — no decisions, no questions, no notes toward its own session. It gets its own scoping session later, and everything you could write into it now is something that session will know better.
The missing 
## Decisions
heading is what a later session reads to know the child has not been scoped. Writing an empty one would make a thin child indistinguishable from a scoped one.
The deferred questions themselves are not copied down. They were announced in the session, they shaped the child's intent, and the child's own interview will raise the live ones again with the siblings' code to read.
Done when every cluster has a directory, an 
epic.md
and a position in the parent's list, and the parent holds no 
spec.md
.
子Epic需创建为细粒度：目录命名为
NN-<slug>
（使用下一个未使用的编号），
epic.md
包含标题和一到两句意图描述，无
## Decisions
标题，并在父节点的有序
Children
列表中添加一行——父节点之前写入的
epic.md
无该列表，此时需添加
Children
章节。无需其他内容——无决策、无问题、无后续会话的笔记。子Epic的范围定义会话会在后续开展，你现在写入的任何内容都可能在后续会话中被更准确的信息替代。
缺失的
## Decisions
标题是后续会话判断子Epic未完成范围定义的标识。写入空的
## Decisions
会导致细粒度子Epic与已完成范围定义的Epic无法区分。
推迟解决的问题本身无需复制到子Epic。这些问题已在会话中宣布，且塑造了子Epic的意图，子Epic自身的访谈会结合前置子节点的代码重新提出相关问题。
完成标志：每个聚类都有对应的目录、
epic.md
文件及父节点列表中的位置，且父节点无
spec.md
文件。

6. Re-scope, when you were called to repair

6. 若需修复则重新定义范围

/archie-design
sends a leaf back here when the how reveals the boundary is wrong. Two shapes, and the user has already chosen which:
  • The leaf is too big. The understanding holds; the unit does not. Run the size backstop below. No re-interviewing.
  • The understanding is wrong. Interview from step 2 with the design session's finding on the frontier, and rewrite the intent and 
    ## Decisions
    in step 4.
Either way, 
spec.md
is dropped the moment the Epic gains children, because Split and Specified are mutually exclusive. Say what the Spec covered before deleting it, and if 
tasks/
exists say what state its Tasks are in — a Task at 
in-progress
or 
ready-for-review
was built against the Spec about to disappear.
当实现过程发现边界不合理时，
/archie-design
会将叶子节点退回此处。存在两种情况，且用户已选择处理方式：
  • 叶子节点范围过大。共识不变，但单元划分不合理。执行以下规模校验机制。无需重新访谈。
  • 共识错误。从步骤2开始重新访谈，将设计会话的发现纳入待解决问题集，并在步骤4中重写意图和
    ## Decisions
    。
无论哪种情况，Epic添加子节点时需立即删除
spec.md
，因为拆分与明确需求是互斥的。删除前需说明该Spec的覆盖范围，若存在
tasks/
目录需说明任务的状态——处于
in-progress
或
ready-for-review
状态的任务是基于即将删除的Spec构建的。

The size backstop

规模校验机制

Applies only after the call is specify. A specifiable Epic can still be too large to build as one leaf — one Spec and a task list nobody wants to run.
Slice it into children on mechanical lines: sequence, surface, one deployable step at a time. This is not a resolution question and it does not reopen the interview — the understanding is complete, the unit is just too big. Say that to the user when you propose the slices, so a split arriving after a specify recommendation does not read as a new round of questions.
仅在选择明确需求后适用。可明确需求的Epic仍可能因范围过大而无法作为单个叶子节点构建——即单个Spec和无人愿意执行的任务列表。
需按机械规则将其拆分为子节点：按顺序、按界面、按可部署步骤拆分。这不属于范围定义问题，无需重新访谈——共识已完整，仅单元规模过大。提出拆分建议时需向用户说明，避免在明确需求建议后提出拆分被误解为新一轮提问。

Editing the tree

编辑Epic树

The tree is a hypothesis, so children can be added, deleted, reordered or further split at any time, in this session or a later one. 
epic-tree.md
fixes the mechanics — numbers are identity, gaps are never backfilled, build order lives in the parent's list.
A Specified child is different. Reordering it, or changing its scope, means the siblings scoped around it may no longer hold. Say so explicitly before touching it:
md
_Heads up:_ `02-password-reset` is Specified. Moving it after `03-sessions` means its Spec was written assuming sessions did not exist yet.
Name what was scoped around it and what may now be stale, then let the user decide. Editing it silently hands them a tree that no longer means what they think it does.
Epic树是一种假设，因此子节点可随时添加、删除、重新排序或进一步拆分，可在本次会话或后续会话中执行。
epic-tree.md
定义了操作机制——编号是唯一标识，不得填补编号空缺，构建顺序由父节点的列表定义。
已明确需求的子Epic有所不同。重新排序或变更其范围，意味着围绕它定义范围的兄弟节点可能不再有效。修改前需明确说明：
md
_注意:_ `02-password-reset`已明确需求。将其移至`03-sessions`之后意味着其Spec是在假设会话不存在的情况下编写的。
说明围绕它定义的范围及可能失效的内容，再交由用户决定。静默修改会导致用户得到的Epic树与其预期不符。