Back to Details

archie-to-spec

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

To spec

生成规格文档

The scoping session reached shared understanding of what this Epic covers; this turns that understanding into 
spec.md
. It asks nothing: every answer it needs has already been given, and the how is 
/archie-design
's, in its own session, writing into the file this one creates.
Read 
references/spec-template.md
 first. It fixes every section of the file.
Requires 
/archie-domain-modeling
for anything durable the synthesis turns up. A scoping session in context has already loaded it; load it if not.
The only file in the tree you write is 
spec.md
, and you write two of its sections as placeholders.
范围界定会议已就该Epic涵盖的内容达成共识；此流程将该共识转化为
spec.md
文档。无需进行任何提问：所需的所有答案均已确定，具体实现方式将由
/archie-design
在独立流程中写入本流程生成的文件。
请先阅读
references/spec-template.md
，该模板定义了文档的所有章节。
依赖：若整合过程中涉及需要持久化的内容，需调用
/archie-domain-modeling
。当前上下文的范围界定会议已加载该功能，若未加载则需手动加载。
整个目录结构中仅需编写
spec.md
文件，其中两个章节需作为占位符写入。

1. Open the Epic

1. 打开Epic

The Epic is the one the session in context just scoped, or the reference the user passed — a root's slug, or 
3.2
, which is child 
02
of child 
03
of the root, resolved down the numbered directories under 
.archie/
.
A Split Epic stops the run. Split and Specified are mutually exclusive, so the Spec belongs to one of its leaves: name the children and ask which one. An Epic that already holds a 
spec.md
is being re-specified — say what the existing Spec covers, and what state any Tasks are in, and get the overwrite agreed before touching it.
Done when you hold one Epic that carries an 
epic.md
, no child directories, and the user's call to specify it.
目标Epic为当前上下文流程刚完成范围界定的Epic，或用户传入的引用——根节点的别名，或
3.2
（即
.archie/
下编号目录中根节点的子节点
03
的子节点
02
）。
若Epic处于**拆分（Split）**状态，则终止当前流程。拆分状态与已指定（Specified）状态互斥，因此规格文档应属于其某个叶子节点：列出子节点并询问选择哪一个。若Epic已存在
spec.md
文档，则表示要重新生成规格文档——需说明现有规格文档涵盖的内容及所有任务的状态，并在获得用户同意覆盖后再进行操作。
当获取到一个包含
epic.md
、无子目录且用户已发起指定请求的Epic时，本步骤完成。

2. Synthesise, do not interview

2. 整合内容，无需询问

The answers are already yours. The session settled them question by question, 
/archie-domain-modeling
wrote the durable ones down, and 
/archie-research
returned the rest. Asking again spends the user's attention on things they have already decided, and it is the one thing this skill must not do. This step has no checkpoint at all.
Assemble the Spec's material from what the session produced: the intent and 
Decisions
in 
epic.md
, the terms and ADRs the session wrote, and the findings under 
research/
.
When the session is not in context — a fresh 
/archie-to-spec 3.2
— read the same material off disk: this Epic's 
epic.md
, every ancestor's 
epic.md
up the path, 
CONTEXT.md
, the ADRs touching this area, the earlier siblings' code, and this Epic's own 
research/
. A gap you can close by reading is not a question; one that genuinely never got answered goes back to the user.
Write in the glossary's vocabulary throughout. Where the synthesis contradicts an ADR, hand it to 
/archie-domain-modeling
rather than quietly overriding it — whether the contradiction amends or supersedes is that skill's call, not yours.
Done when every section of the template has its material, and you can say for each one which part of the session it came from.
所有答案均已就绪。范围界定会议已逐一确定这些内容，
/archie-domain-modeling
已记录需要持久化的部分，其余内容由
/archie-research
返回。再次询问会占用用户时间处理已决定的事项，这是本技能绝对禁止的操作。本步骤无任何检查点。
从会议产出内容中整合规格文档的素材：
epic.md
中的目标与
Decisions
（决策）章节、会议记录的术语与ADRs（架构决策记录），以及
research/
目录下的调研结果。
当无当前上下文流程时——例如直接调用
/archie-to-spec 3.2
——需从磁盘读取以下素材：该Epic的
epic.md
、路径上所有父节点的
epic.md
、
CONTEXT.md
、涉及该领域的ADRs、早期同级节点的代码，以及该Epic自身的
research/
目录内容。可通过读取填补的信息缺口无需提问；若确实存在从未被解答的问题，则需反馈给用户。
全程使用术语表中的词汇。若整合内容与ADR冲突，需将该问题提交给
/archie-domain-modeling
处理，而非直接覆盖——冲突内容是修正还是替代ADR，由该技能决定，而非本技能。
当模板的每个章节都已准备好素材，且能说明每个章节内容来源于会议的哪一部分时，本步骤完成。

3. Write the Spec

3. 编写规格文档

Write 
spec.md
beside the Epic's 
epic.md
, following the template exactly, 
Epic:
reference included.
## Implementation Decisions
and 
## Testing Decisions
each get the single line 
_Not yet designed._
and nothing else. Those two are the how, they are 
/archie-design
's to write, and that literal line is what tells every later reader — the user, 
/archie-architect
, 
/archie-to-tasks
— that this leaf has a Spec and no design yet.
Two rules govern the rest, and they are what keeps a Spec true weeks later:
  • Name surfaces, never file locations. A surface is what other code or a person calls: an endpoint and its shape, a URL, a CLI flag, an exported API, a module or component name, a package. Those are what was agreed and they survive a refactor; 
    apps/api/src/shift/shift.controller.ts
    does not, and the code is where that lives.
  • User Stories
    is long.     Every aspect of the work, one story each, in the template's 
    As a … I want … so that …
    form. 
    /archie-to-tasks
    slices against this list, so a thin list hides work rather than removing it.
Anything the session settled that reaches past this Epic belongs in 
CONTEXT.md
or 
docs/adr/
, not only in the Spec: the tree is disposable and the Spec goes with it. Invoke 
/archie-domain-modeling
on anything still unrecorded before you finish.
Done when 
spec.md
exists, every section other than the two placeholders carries content, and no line names a path.
在Epic的
epic.md
旁编写
spec.md
，严格遵循模板格式，包含
Epic:
引用信息。
## Implementation Decisions
（实现决策）和
## Testing Decisions
（测试决策）章节仅需写入单行内容
_Not yet designed._
（尚未设计）。这两个章节属于实现方式范畴，由
/archie-design
负责编写，该占位符内容可告知后续所有阅读者——用户、
/archie-architect
、
/archie-to-tasks
——该叶子节点已有规格文档，但尚未完成设计。
其余章节需遵循以下两条规则，这是确保规格文档长期有效的关键：
  • 命名对外接口，而非文件路径。 对外接口指其他代码或用户调用的对象：如接口端点及其结构、URL、CLI标志、导出的API、模块或组件名称、包。这些是已达成共识的内容，在重构后依然有效；而
    apps/api/src/shift/shift.controller.ts
    这类文件路径则会随重构变化，代码的具体位置应在代码中体现。
  • User Stories
    （用户故事）需详尽。     工作的每个方面都需单独编写一个用户故事，遵循模板的“作为……，我希望……，以便……”格式。
    /archie-to-tasks
    会基于该列表拆分任务，因此过于简略的列表会隐藏工作量，而非减少工作。
会议中确定的超出该Epic范围的内容，应写入
CONTEXT.md
或
docs/adr/
，而非仅存在于规格文档中：目录结构可随时替换，规格文档会随Epic迁移。完成前，需调用
/archie-domain-modeling
记录所有尚未持久化的内容。
当
spec.md
已生成、除两个占位符章节外其余所有章节均有内容，且无任何行提及文件路径时，本步骤完成。

4. Hand off

4. 移交流程

Report in one line — the path — then name 
/archie-design
as the next step and stop. The Epic is now Specified and undesigned, and nothing can be built from it until the how is settled.
用一行内容报告文档路径，然后指定
/archie-design
为下一步流程并终止。此时Epic处于**已指定（Specified）**但未设计状态，在确定实现方式前无法开展任何开发工作。