Back to Details

better-plan

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

ForgeDoc

ForgeDoc

You write semantic markup only. A prebuilt runtime supplies all styling, layout, interactivity, persistence and feedback collection.
Do not write 
<style>
, 
<script>
, 
class=
, 
id=
, 
role=
, 
aria-*
, option letters (
A
/
B
/
C
), section numbers (
1.2.1
), or stage numbers. Every one of those is derived. Writing them by hand either fails the build or goes stale.
Read 
CHEATSHEET.md
for the full tag list. It fits on one page; keep it open. 
REFERENCE.md
, beside it, is the per-attribute detail — reach for it only when the cheatsheet leaves a question open.
你只需编写语义标记即可。预构建的运行时会提供所有样式、布局、交互性、持久化和反馈收集功能。
请勿编写
<style>
、
<script>
、
class=
、
id=
、
role=
、
aria-*
、选项字母（
A
/
B
/
C
）、章节编号（
1.2.1
）或阶段编号。这些内容均由运行时自动生成。手动编写这些内容要么会导致构建失败，要么会过时失效。
查看
CHEATSHEET.md
获取完整标签列表，内容仅一页，请保持该文档打开。旁边的
REFERENCE.md
包含每个属性的详细说明——仅当速查表无法解答你的疑问时再查阅它。

Producing a plan

生成规划文档

  1. forgedoc new <name>
    — or write the skeleton yourself. It must contain these two lines, byte for byte: the first in 
    <head>
    , the second as the last line of 
    <body>
    .
    html
    <style>/*@DOC_CSS@*/</style>
<script>//@DOC_JS@</script>
    The styles go up top so the reader never sees a frame of unstyled markup; the script goes last so every element upgrades with its children present.
  2. Write the document inside a single 
    <doc-page doc-id="a-unique-slug">
    . The 
    doc-id
    is mandatory — it namespaces the reader's stored answers, and without it two plans opened from disk can overwrite each other.
  3. forgedoc build DOC_<name>.html
    The build validates first and writes nothing if validation fails. Read the errors, fix them, and run it again. Each error carries a file, a line, a column, a rule id and a concrete fix. 
    --format=json
    on 
    forgedoc validate
    gives you the same thing as structured data.
    The output links a version-pinned CDN and stays around 15 kB, so it is safe to commit. Pass 
    --offline
    only when the reader genuinely has no network — it embeds the whole runtime, which is ~3.5 MB once a Mermaid figure is present, and writes into 
    .temp/
    because that file should never be committed.
  1. forgedoc new <name>
    —— 或者自行编写骨架文档。文档必须包含以下两行内容，字节级完全一致：第一行放在
    <head>
    中，第二行作为
    <body>
    的最后一行。
    html
    <style>/*@DOC_CSS@*/</style>
<script>//@DOC_JS@</script>
    样式放在顶部是为了让读者永远不会看到未样式化的标记帧；脚本放在最后是为了确保每个元素在其子元素加载完成后再进行升级。
  2. 在单个
    <doc-page doc-id="a-unique-slug">
    标签内编写文档内容。
    doc-id
    是必填项——它为读者存储的答案提供命名空间，如果没有它，从磁盘打开的两个规划文档可能会互相覆盖。
  3. forgedoc build DOC_<name>.html
    构建过程会先进行验证，如果验证失败则不会生成任何文件。请阅读错误信息，修复问题后重新运行命令。每条错误信息都会包含文件、行号、列号、规则ID以及具体的修复方案。在
    forgedoc validate
    命令后添加
    --format=json
    参数，可获取结构化的错误数据。
    输出文件会链接到版本固定的CDN，大小约为15 kB，因此可以安全地提交到版本控制系统。仅当读者确实没有网络时才使用
    --offline
    参数——该参数会嵌入整个运行时环境，当文档中包含Mermaid图表时，文件大小约为3.5 MB，并且会写入
    .temp/
    目录，因为该文件绝不应该被提交。

What the runtime derives, so you never type it

运行时自动生成的内容（无需手动编写）

You writeThe runtime produces
<doc-section title="Data model">
The number 
2.1
, the id 
sec-data-model
, the heading element, the TOC entry
<doc-choice question="…">
with options		Letters 
A
/
B
/
C
, an "Other" option with a textarea, a note field, 
QUESTION 3 · SINGLE CHOICE
, the id 
q-…
, radiogroup ARIA
<doc-stage title="…">
The stage number, starting at 0
<doc-ref to="sec-data-model">
The live text "Section 2.1"
<doc-term href="…">
First-mention styling, distinct from repeats
你编写的内容运行时生成的内容
<doc-section title="Data model">
编号
2.1
、ID
sec-data-model
、标题元素、目录条目
<doc-choice question="…">
（含选项）		字母
A
/
B
/
C
、带文本框的“其他”选项、备注字段、
QUESTION 3 · SINGLE CHOICE
、ID
q-…
、ARIA单选组
<doc-stage title="…">
阶段编号，从0开始
<doc-ref to="sec-data-model">
动态文本“Section 2.1”
<doc-term href="…">
首次提及样式，与重复提及区分开

Writing well

编写规范

  • Ask real questions. A plan with no 
    doc-choice
    collects no feedback, and the validator warns about it. Put a question wherever you made a judgement call the reader might disagree with, and mark your suggestion 
    recommended
    .
  • Every roadblock states its resolution. 
    doc-blocker
    requires a 
    doc-action
    . This is enforced, not advisory — a roadblock with no way out is the failure the whole library exists to prevent.
  • Prefer 
    doc-figure type="mermaid"
    over hand-drawn SVG.     Five lines of Mermaid replaces a few hundred lines of hand-placed coordinates, renders in the document's own colours, and is far more reliable to write.
  • Use 
    doc-ref
    , never "see Stage 5".     Numbering is automatic; a hardcoded reference is a latent bug from the moment a stage is inserted above it.
  • Use plain HTML for prose. 
    <p> <ul> <ol> <li> <code> <a> <strong> <em>
    are all styled. There is deliberately no tag for them.
  • Presets, not CSS. 
    <doc-page density="compact" measure="wide">
    is validated and consistent; hand-written CSS is not.
  • 提出真实问题：如果规划文档中没有
    doc-choice
    标签，则无法收集反馈，验证器会发出警告。在你做出可能会引发读者异议的判断时，请添加问题，并将你的建议标记为
    recommended
    。
  • 每个障碍都需说明解决方案：
    doc-blocker
    标签必须搭配
    doc-action
    标签使用。这是强制要求，而非建议——没有解决方案的障碍正是整个库要避免的失败情况。
  • 优先使用
    doc-figure type="mermaid"
    而非手绘SVG    ：五行Mermaid代码可以替代数百行手动定位的坐标，并且会使用文档自身的颜色渲染，编写起来也可靠得多。
  • 使用
    doc-ref
    ，绝不要写“参见第5阶段”    ：编号是自动生成的；从插入阶段的那一刻起，硬编码的引用就会成为潜在的bug。
  • 使用纯HTML编写正文：
    <p> <ul> <ol> <li> <code> <a> <strong> <em>
    这些标签都会被自动样式化，因此无需为它们专门设置标签。
  • 使用预设而非CSS：
    <doc-page density="compact" measure="wide">
    是经过验证且一致的设置；手动编写的CSS则不具备这样的特性。

Reading a pasted bucket back

读取粘贴的反馈内容

A reader sends you a block that begins 
=== FB v1 ·
. It is self-contained: it carries the question text and the chosen option labels verbatim, so you do not need the original file to interpret it.
text
=== FB v1 · vendor-orders · 2026-07-28T10:22:31Z · 2 items ===

[1] ANSWER q-should-read-state-be-shared
q: Should read state be shared across the vendor team?
a: Yes — shared team inbox
n: only if we can still see who marked it read

[2] COMMENT sec-what-we-are-building
at: 1 What we are building
> Vendors get told the moment a new order lands
c: is this the payment webhook or the order row?

=== end FB v1 ===
Fields: 
q:
question, 
a:
a chosen answer label (repeated for a multi answer), 
n:
a note about the answer, 
>
the quoted excerpt, 
c:
the reader's comment, 
at:
where in the document. A field's continuation lines are indented by exactly three spaces.
A comment on a diagram, an image or a code block has no selectable text to quote, so its 
>
line is a descriptor instead — 
> doc-figure · How a plan travels from the agent to the reader and back
. The anchor id is generated (
blk-figure-2
), so resolve it by the caption or filename in that descriptor, not by the id.
读者会发送一个以
=== FB v1 ·
开头的内容块。该内容块是自包含的：它包含了问题文本和所选选项的标签原文，因此你无需查看原始文件即可解读它。
text
=== FB v1 · vendor-orders · 2026-07-28T10:22:31Z · 2 items ===

[1] ANSWER q-should-read-state-be-shared
q: Should read state be shared across the vendor team?
a: Yes — shared team inbox
n: only if we can still see who marked it read

[2] COMMENT sec-what-we-are-building
at: 1 What we are building
> Vendors get told the moment a new order lands
c: is this the payment webhook or the order row?

=== end FB v1 ===
字段说明：
q:
问题，
a:
所选答案标签（多选时会重复），
n:
关于答案的备注，
>
引用的摘录内容，
c:
读者的评论，
at:
文档中的位置。字段的续行需缩进恰好三个空格。
针对图表、图片或代码块的评论没有可选择的文本可引用，因此其
>
行是描述性文本——例如
> doc-figure · How a plan travels from the agent to the reader and back
。此时会生成锚点ID（如
blk-figure-2
），因此请根据描述中的标题或文件名来定位，而非锚点ID。

Receipt rules — follow these exactly

接收规则——严格遵守以下规则

  1. Resolve each item by anchor id first, quoted text second. The anchor id is the token after 
    ANSWER
    or 
    COMMENT
    .
  2. The option label is authoritative over the option key. If the label and the key disagree, or the anchor no longer exists in your copy of the document, ask the reader. Never guess which option they meant.
  3. A malformed item invalidates only itself. Process every other item and report the broken one back to the reader.
  4. Never attribute an answer to a question whose text does not match verbatim. If the question was reworded between the version they answered and the version you are holding, that is a question to ask, not a match to make.
  5. An 
    a:
    line under an Other answer is the reader's own words    , not one of your option labels. Treat it as a new proposal.
  1. 优先通过锚点ID解析每个条目，其次是引用文本：锚点ID是
    ANSWER
    或
    COMMENT
    后的标识。
  2. 选项标签比选项键更权威：如果标签和键不一致，或者你的文档副本中已不存在该锚点，请询问读者。切勿猜测他们指的是哪个选项。
  3. 格式错误的条目仅会使自身失效：处理所有其他条目，并将损坏的条目反馈给读者。
  4. 切勿将答案归因于文本不完全匹配的问题：如果读者回答的版本与你当前持有的版本之间问题被重新措辞，这是需要询问的问题，而非直接匹配。
  5. “其他”答案下的
    a:
    行是读者自己的表述    ，而非你提供的选项标签。请将其视为新的提案。

After you have read it

读取反馈后的操作

Regenerate the plan with the decisions folded in. Answered questions become 
<doc-chip kind="confirmed">
entries rather than open 
doc-choice
blocks — a question the reader has already settled should not be asked twice. Tooling can do this incrementally with 
ForgeDoc.chips.add({kind: 'confirmed', text: '…'})
.
重新生成包含已纳入决策的规划文档。已回答的问题会变为
<doc-chip kind="confirmed">
条目，而非开放的
doc-choice
块——读者已经确定的问题不应再次被询问。可以使用
ForgeDoc.chips.add({kind: 'confirmed', text: '…'})
工具来逐步完成此操作。

Budget

预算

A plan of the size of the reference document should cost under 4,000 output tokens of markup. If you find yourself writing layout, colours, or numbers, you are writing something the runtime already does.
参考文档规模的规划文档，其标记的输出令牌数应低于4000。如果你发现自己在编写布局、颜色或编号内容，说明你正在编写运行时已自动生成的内容。