buildnotes

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Buildnotes

A build story explains a feature to someone who knows what the product does but wasn't in the room: what problem it solves, how it works, and the two or three decisions that shaped it. It is written for people outside the team.

The record is the source, not the story. Issues, PRs, commits and reviews say what happened and in what order, and they are a small slice of the picture. Read the product the way its users meet it, and find the angle a product marketer would: what changed for users, and why it is worth their attention. Organize by idea, not by date.

Three failures this skill exists to prevent:

The play-by-play. The development process narrated in order, with timestamps, PR numbers and who reviewed what.
The changelog in prose. Every change listed, no argument.
The press release. Confident claims with nothing behind them.

The cure for all three is the same. Find the few ideas and decisions that made the feature what it is, explain each at the level the reader needs, and back each one with real evidence.

构建故事向一个了解产品能做什么、但并未参与其中的人解释一项功能：它解决什么问题、如何运作，以及塑造它的两三个决策。故事写给团队之外的人。

记录才是来源，而不是故事本身。Issue、PR、commit 和 review 说明发生了什么以及发生的顺序，但它们只是全局的一小部分。要像用户接触产品那样去阅读产品，并找到产品营销人员会寻找的切入角度：用户身上发生了什么变化，为什么值得关注。按理念组织，而不是按日期。

这个 skill 的存在是为了避免三种失败：

流水账。 按顺序讲述开发过程，附带时间戳、PR 编号以及谁 review 了什么。
用散文写 changelog。 列出每一项变化，却没有论证。
新闻稿。 充满自信的断言，背后却没有依据。

三种问题的解法相同。找出让该功能成为今天模样的少数几个理念和决策，按读者需要的深度逐一解释，并用真实证据支撑每一个理念。

Output

输出

The request may open with the output it wants, as in

/buildnotes video tech explainer of our latest PR

. Read the first word:

post
: the page. This is the default.
video
: the page and its motion cut. The cut is made from the finished post, so write the post first, then go straight on to step 9 without offering it.
deck
: the page and its deck, slides to click through and a PDF. The deck is built from the motion cut's scene script, so write the post and
```
motion.json
```
first, then go on to step 10.
Anything else: there is no output word. The whole request is the brief, and a request for a video, a reel or a quick version still means
```
video
```
.

The rest of the request is the brief: the subject, plus anything about flavor, reader or style, in plain words. "Tech explainer" or "deep dive" means the technical deep dive, and "launch post" or "release notes" means the release story. Read these as you would any other request; they are not fixed values. When it's unclear whether the author wants a video, don't ask: write the post and offer the cut in the hand-off, as step 9 says.

请求可能以所需输出开头，例如

/buildnotes video tech explainer of our latest PR

。读取第一个词：

post
：页面。这是默认输出。
video
：页面及其动效短片。短片根据完成后的页面制作，因此先写页面，然后直接进入步骤 9，不再另行询问。
deck
：页面及其 deck，包括可逐页点击的幻灯片和 PDF。deck 根据动效短片的场景脚本构建，因此先写页面和
```
motion.json
```
，然后进入步骤 10。
其他任何内容：没有输出关键词。完整请求就是创作简报（brief）；即使请求要求视频、reel 或快速版本，也仍然视为
```
video
```
。

请求的其余部分就是创作简报：主题，以及用自然语言表达的体裁、读者或风格要求。“Tech explainer”或“deep dive”表示技术深度解析；“launch post”或“release notes”表示发布故事。按普通请求理解这些词；它们不是固定值。如果不清楚作者是否想要视频，不要追问：先写页面，并按照步骤 9 在交付时主动提出可制作短片。

The rules

规则

Each rule carries the fault that taught it, and links to the reference that holds the detail where there is one.

A starting point, not the manual. Go only as deep as it takes to get the idea across; the docs carry the rest. Show one way to try it and link the docs, unless the author asks for a full guide. A post says what changed in a way that stays true; the docs hold the scenarios. Listing every case where a behaviour applies (each credential source, each retry, each flag) reads as a support page and goes stale with the next release, so keep it directionally right and link the docs for the cases. A deep dive the author asked for is different: that reader wants the mechanism and its cases, and the post can sit between a launch post and a reference page. (Fault: a closing chapter touring every setup path, a menu, an agent tool's argument, two CLI flags and a help screen, for a feature you set up once.)
Earn every detail. Keep a date, number, quote, tool name, review comment or code excerpt only if the reader would understand the feature less without it. Nothing in the record is owed a place. Outside a deep dive, leave out edge-case behaviour (no JavaScript, reduced motion, keyboard shortcuts) and don't list everything a UI contains; readers assume a familiar control works the familiar way. (Fault: a launch post for video chapters that explained what happens with motion reduced and walked through every key.) (Fault: an adversarial-review quote that added color and no understanding.)
Before, then after. When the change replaces something, show the old way first and the new way next, labelled, ideally side by side near the top, so the reader is anchored before the explanation starts. Give a sentence of what came before; don't start cold, and don't recount the whole history. (Fault: the new figure in chapter one and the old one two chapters later, so a reader scrolling past saw the change in reverse.)
Lead with what people can do. The headline is the capability users see, not the mechanism behind it. The mechanism leads only in a deep dive, when the author asks, or when it is what users touch. brief.md (Fault: a post about one-click preview links whose centerpiece was how the scheduler pools build machines.)
Don't name yourself in the title. The title says plainly what shipped; the angle and the play go in the dek and the opening. The title and chapter headings are about what the reader gets; the product and company name stay out of them, and the prose names the product once where a newcomer needs it. In a feed where every title names its own company, the name stops meaning anything. craft.md (Fault: "Tell Releases what you care about".)
Ideas, not chronology. Chapters are concepts, challenges or parts of the system, never days or PRs. Mention timing only when it is the point, and then in days. Iteration labels ("round one", "as it ships") are fine; clock times and commit-by-commit narration are not. story.md (Fault: "At 14:56 UTC the decision went the other way; the API half merged at 15:33.")
Show the turn, briefly. A chapter that matters names the decision, the alternative that lost, and why, in a few sentences. (Fault: "we added per-branch databases" with no word on why not one shared database with a schema per branch.)
Process detail is optional. Review comments, PR counts, timelines, and which tools or agents did the work are never required. Include one only when it changes the reader's picture: a review that found a flaw they would wonder about, a reversal that explains an odd-looking design. If coding agents or automated reviewers did part of the work, say nothing about it by default and don't ask; the
```
how-made
```
module is there if the author wants it. (Fault: three review quotes in a row, each crediting a reviewer, none needed to understand the design.)
References are rare and reachable. Link only what the reader can open and would want: public docs, the product, an open-source repo, a few key PRs in a public deep dive. In a private repo, link nothing internal. The text never depends on a link. story.md (Fault: a superscript issue number on every other paragraph of a post about a closed-source product.)
Confirm every URL before you use it. Link to or measure only an address you have seen: in the record, the code's routes, the sitemap, or a link on the live site. Open it and get a 200 first. Never build one by guessing a slug or an id;
```
lint.mjs
```
opens every link and fails on one that doesn't load. (Fault: a speed check on a made-up collection address, whose 404 then became a question for the author.)
Every number has a source, and earns its place. It comes from the dossier, a file, or a command you ran for this post. Prefer numbers about the product ("a preview is ready about 40 seconds after you push") over numbers about the process (lines changed, PRs merged). Masthead stats are off by default; keep one only if a stranger gets it cold. evidence.md (Fault: "cut latency by ~40%" with no measurement anywhere; a masthead reading "Write paths: 1".)
Understood beats exact. Better a reader who gets the idea from a detail that's close enough than one who gets every detail right and misses the idea. Never mislead, but don't chase precision a reader wouldn't notice. If confirming a claim would take production data, the beat is about running the service: cut it or say less before you investigate. evidence.md (Fault: a chapter about a cache's hit rate in a post for the product's users, and a trip into server logs to back it up.)
Name ideas, not identifiers. In the story, say what a thing does; save function names, flags and enum values for the try-it section and code blocks. story.md (Fault: a chapter whose sentences are strung between
flush()
,
commit()
and
edit_rev
.)
Real code, only where the code is the idea. Copied from the shipped commit, at most about 15 lines, captioned with the file name only, cuts marked
```
…
```
. Never present illustrative code as the real thing. (Fault: a tidy snippet that matches nothing in the repo.)
One visual per chapter, at most, and it must explain. Decoration goes. visuals.md (Fault: a diagram that restates the heading.)
Infer the angle; don't invent the facts. Implications, context and hooks the record never states are yours to find. Motives, quotes, events and numbers are not: describe what the record shows the change does, and when it doesn't say why, leave the reason out and put it on the open questions. (Faults: a post that only restates the PRs; a plausible but fictional origin story; "no fallback model, because another model's score wouldn't mean the same thing", stated as fact with nothing behind it.)
Plain, scannable voice. "We" (or "I"), plain English (STE-lite: short sentences, active voice, one term per thing; strict STE only if the author asks), bold the key decision about once per chapter, lists for three or more items. Sound like a person, not a writer. story.md (Fault: "We added three things. A retry… A queue… And an alert…", a list pretending to be a paragraph.)
Safe to publish. No secrets, tokens, internal hostnames, customer names, personal paths or emails, internal links, or unreleased plans unless the author clears them. (Fault: a terminal excerpt with a live API key in it.)

每条规则都对应一个促成它的教训，并在有参考资料时链接到保存详细说明的文档。

起点，而不是手册。 只深入到足以把概念讲清楚的程度；其余细节由文档承载。除非作者要求完整指南，否则展示一种尝试方式并链接文档。文章要说明经得起时间检验的变化，具体使用场景则由文档承载。逐一列出行为适用的每种情况（每种凭据来源、每次重试、每个 flag）会读起来像支持页面，并会在下一次发布时过时，因此应保持方向正确，并链接文档说明具体情况。如果作者明确要求深度解析，则情况不同：这类读者需要了解机制和各种场景，文章可以处于发布故事与参考页面之间。（教训：在一篇面向只设置一次的功能的文章结尾，逐一介绍所有设置路径、菜单、某个 Agent 工具的参数、两个 CLI flag 和帮助页面。）
让每个细节都物有所值。 只有当删掉某个日期、数字、引述、工具名、review 意见或代码摘录后，读者会更难理解功能时，才保留它。记录中的任何内容都不因存在就理应占位。除深度解析外，省略边缘场景行为（无 JavaScript、减少动态效果、键盘快捷键），也不要罗列 UI 中的所有内容；读者默认熟悉的控件会以熟悉的方式工作。（教训：一篇介绍视频章节的发布文章，解释了减少动态效果时会发生什么，并逐步走遍每个按键。） （教训：引用一条充满对抗性的 review 意见，只添趣味却没有增加理解。）
先展示之前，再展示之后。 如果变更取代了原有做法，先展示旧方式，再展示新方式，并加上标签，最好在靠前位置并排呈现，让读者在解释开始前先有参照。用一句话说明此前是什么样；不要冷启动，也不要重述整段历史。（教训：新图出现在第一章，旧图却到两章之后才出现，导致滚动浏览的读者看到的是倒序变化。）
以人们能做什么开头。 标题写用户看得见的能力，而不是背后的机制。只有在深度解析、作者明确要求，或者机制本身就是用户直接接触的内容时，才先讲机制。brief.md （教训：一篇关于一键预览链接的文章，却把调度器如何池化构建机作为核心。）
标题中不要自报名称。 标题直白说明发布了什么；切入角度和叙事方式放在 dek 与开头。标题和章节标题讲读者获得什么；产品名和公司名不进入标题，正文只在新用户需要时提一次产品。在每个标题都带自家公司名的信息流中，公司名会失去意义。craft.md （教训：“Tell Releases what you care about”。）
按理念组织，而不是按时间顺序。 章节围绕概念、挑战或系统中的某一部分展开，绝不按天或按 PR 划分。只有时间本身是关键信息时才提及，而且以天为单位。迭代标签（“第一轮”“发布时”）可以；时钟时间和逐 commit 叙述则不行。story.md （教训：“UTC 时间 14:56 时，决策转向了另一边；API 部分在 15:33 合并。”）
简要呈现转折。 重要章节要用几句话点明决策、落选的备选方案，以及为什么选择前者。（教训：只写“我们添加了按分支独立的数据库”，却完全没说明为什么没有采用一个共享数据库、再为每个分支设置独立 schema。）
流程细节是可选的。 review 意见、PR 数量、时间线，以及哪些工具或 Agent 完成了工作，都不是必需内容。只有当某项流程细节会改变读者对功能的认识时才加入：例如，一次 review 找出了读者也会疑惑的缺陷；一次方向反转解释了某个看起来奇怪的设计。如果 coding Agent 或 automated reviewer 完成了部分工作，默认不要提及，也不要追问；如果作者想讲，
```
how-made
```
module 可以处理。（教训：连续引用三条 review 意见，每一条都在向 reviewer 致谢，却没有一条有助于理解设计。）
引用要少且可达。 只链接读者能够打开且愿意打开的内容：公开文档、产品、开源仓库，以及公开深度解析中的少数关键 PR。在私有仓库中，不链接任何内部内容。正文不得依赖链接才能被理解。story.md （教训：在一篇介绍闭源产品的文章里，每隔一段就加上一个 Issue 编号上标。）
使用前确认每个 URL。 只能链接或测量你实际见过的地址：记录中的地址、代码里的 routes、sitemap 或线上站点上的链接。打开并确认返回 200 后再使用。绝不能根据猜测的 slug 或 id 拼地址；
```
lint.mjs
```
会打开每个链接，只要一个无法加载就会失败。（教训：对一个编造的 collection 地址做速度检测，结果它的 404 反而变成了向作者提出的问题。）
每个数字都有来源，也值得占据篇幅。 数字必须来自 dossier、文件，或你为本文运行的命令。优先使用与产品有关的数字（“push 后约 40 秒即可预览”），而不是流程数字（改动行数、合并的 PR 数）。报头统计默认关闭；只有陌生人一眼就能理解时才保留一个。evidence.md （教训：写出“将延迟降低约 40%”，却没有任何测量依据；报头却写着“Write paths: 1”。）
被理解比绝对精确更重要。 与其让读者记住每个完全准确的细节却错过核心，不如让读者通过一个足够接近的细节理解概念。绝不能误导，但也不要追逐读者不会注意到的精度。如果核实某个论断需要生产数据，而该章节讲的是如何运行服务，那么在调查之前先删掉它或收敛表述。evidence.md （教训：在一篇面向产品用户的文章中用章节讨论 cache 命中率，却为此进入服务器日志寻求依据。）
讲理念，不讲标识符。 在叙事中说明某个东西的作用；函数名、flag 和 enum 值留到“试一试”章节及代码块中。story.md （教训：一节文章由
flush()
、
commit()
和
edit_rev
等名称串联而成。）
只有当代码本身承载核心概念时，才使用真实代码。 代码复制自已发布的 commit，最多约 15 行；说明文字只写文件名；删节处用
```
…
```
标记。绝不能把示意代码冒充为真实代码。（教训：一段整洁的代码与仓库中的任何内容都不匹配。）
每章最多一张视觉图，而且它必须能解释内容。 删除纯装饰内容。visuals.md （教训：一张只是在复述标题的图。）
推断切入角度，但不要虚构事实。 记录没有明说的含义、背景和 hook，需要由你来找。动机、引述、事件和数字则不能虚构：描述记录所展示的变更行为；如果记录没有说明原因，就不要补写原因，而应将其列入 open questions。（教训：一篇文章只是复述 PR；编造了一个看似合理的起源故事；把“没有 fallback model，因为另一个 model 的 score 没有可比性”写成事实，却毫无依据。）
平实、便于扫读的语气。 使用“我们”（或“我”），采用平实英文（STE-lite：短句、主动语态、一件事只用一个术语；除非作者要求，否则只遵循 STE）。每章大约一次加粗关键决策；三个及以上项目使用列表。听起来要像人，而不是像写作者。story.md （教训：“我们添加了三样东西。一个重试……一个队列……还有一个告警……”，把列表伪装成段落。）
可以安全发布。 未经作者许可，不得包含 secret、token、内部主机名、客户名称、个人路径或邮箱、内部链接，以及未发布的计划。（教训：一段终端摘录中暴露了仍然有效的 API key。）

Flavors and size

体裁与篇幅

Pick one in Scope. It sets the reader, the level of detail and the defaults below.

	Release story	Build story (default)	Technical deep dive
Reader	Users and prospective users	Developers who know the product	Engineers who want the mechanism
Answers	What's new, why it matters, what changes for you	What we built, how it works, what shaped it	How it works inside, the trade-offs, the edge cases
Detail	Product and outcomes; internals in a sentence	Concepts and decisions; internals only where they explain something the reader sees	Mechanisms, data structures, failure modes
Visuals	Screenshots, before/after, one simple flow	Diagrams, motion, before/after	Diagrams, terminal runs, charts
Code	A usage example at most	Only where the code is the idea	Where it helps
Process detail	None	Only where it explains a design	Where it teaches
Operator and admin tooling	Out	Out, unless it explains a design	In, when it teaches
References	Docs and product links	A short "Further reading" at most	Key PRs and docs, if public

Size it to the subject, not the flavor. Word counts are ceilings with no minimum (release story up to 1,200, build story up to 2,500, deep dive usually under 3,000; chapters, visuals and sizing by scope in story.md). A small change gets a note: a paragraph or three, no chapters, no masthead, at most one visual.

Say when it isn't worth a write-up. A subject is thin when it is small (a typo, a one-line fix, a dependency bump, a refactor users never see) and also when it is standard practice: work any capable team would do the usual way, like self-hosting web fonts, adding chapters to a video player or writing a sitemap. Readers already know how those work, so explaining one at length talks down to them. This holds even when the author asks for a deep dive; standard practice earns a post only if it went somewhere unusual (a measured result, a surprising failure, a choice most teams would make differently). For a thin subject, check the nearby work first. If the thin change is clearly one piece of a bigger idea (the same release, the same effort, work the author would plainly see as one story), write that post and say in the hand-off, in a sentence, that you widened the scope and why. The author would rather have a draft to react to than a question. Stop and ask only when the bigger idea is a real change of subject: a different feature, a much larger post, or work the author might not want public. Then say in a sentence or two why the change alone isn't a post (the author needs the verdict, not the full case), name the bigger idea and the angle you'd lead with, and ask whether to write that instead (check it first with

--pr

). Often the bigger idea is an arc across several modest changes from the same weeks ("three ways our examples got easier to follow"), where each change is a section, not a post. If there is no bigger idea, say plainly it's not worth a post and offer a short note or a line in a larger release.

从 Scope 中选择一种体裁。它决定目标读者、细节深度和以下默认值。

	发布故事	构建故事（默认）	技术深度解析
读者	用户和潜在用户	了解产品的开发者	想了解机制的工程师
回答的问题	有什么新变化、为何重要、对用户有什么影响	我们构建了什么、如何运作、哪些因素塑造了它	内部如何运作、有哪些权衡、有哪些边缘场景
细节	产品和结果；内部机制只用一句话	概念和决策；只有能解释读者所见时才涉及内部机制	机制、数据结构、故障模式
视觉素材	截图、前后对比、一个简单流程	图示、动效、前后对比	图示、终端运行、图表
代码	最多一个用法示例	仅在代码本身承载核心概念时使用	在有助于说明时使用
流程细节	无	仅在能解释设计时使用	在能提供教学价值时使用
Operator 和管理员工具	不涉及	不涉及，除非有助于解释设计	在能提供教学价值时涉及
引用	文档和产品链接	最多一个简短的“延伸阅读”	如果内容公开，则包含关键 PR 和文档

篇幅应按主题确定，而不是按体裁决定。 字数上限没有下限（发布故事最多 1,200，构建故事最多 2,500，技术深度解析通常少于 3,000；章节、视觉素材和篇幅按 story.md 中的 Scope 确定）。小改动写成一则 note：一到三段，不分章节，无报头，最多一张视觉图。

判断是否值得专门写一篇文章。 当主题既很小（拼写修正、一行修复、依赖升级，或用户看不到的 refactor），又属于标准实践时，它就很单薄：任何有能力的团队都会用常规方式完成这类工作，例如 self-hosting web fonts、为视频播放器添加章节或编写 sitemap。读者已经了解这些工作方式，因此长篇解释是在俯视读者。即使作者要求深度解析，这一点也不变；标准实践只有在走向了不寻常的方向时才值得写成文章（可衡量的结果、令人意外的问题，或大多数团队会做出不同选择的地方）。

遇到单薄主题时，先检查附近的工作。如果这项单薄改动明显是某个更大想法的一部分（同一场发布、同一份投入，或者作者显然会把它视为同一个故事），就写那篇更完整的文章，并在交付时用一句话说明你扩大了范围以及原因。作者更愿意拿到可以反馈的草稿，而不是一个问题。只有当更大的想法确实改变了主题时才停下来询问：不同的功能、大得多的文章，或者作者可能不希望公开的工作。此时用一两句话说明为什么这项改动单独成篇不合适（作者需要的是结论，而不是完整论证），指出更大的想法及你准备采用的主要角度，并询问是否改为写它（先使用

--pr

检查）。更大的想法通常是数周内一系列较小改动构成的连续弧线，例如“我们的示例变得更容易理解的三种方式”；这时每项改动应成为文章中的一节，而不是一篇独立文章。如果不存在更大的想法，就明确说明这项工作不值得单独写一篇，并提议写一则短 note，或放进更大的发布内容中。

Workflow

工作流

1. Scope

1. 确定范围

Settle these from the request, the repo and the defaults. Don't ask about scope on its own; if something is truly unclear, fold it into the one message in step 3.

Subject. The idea the post is about. Whatever the author points at (an issue, a few PRs, a search phrase, a commit range, a path) is a breadcrumb, not a boundary. Related work landing around the same time (the dossier's Nearby work) often belongs to the same idea, and some of what was pointed at may not. Draw the boundary around the idea.
Flavor and size. Default: build story for a real feature, a note or "not worth a post" for a thin one. If the author asks for a technical or engineering post, that's the deep dive: the internals, operator tooling and trade-offs can be the subject, and the reader-facing tests in craft.md and brief.md bend to that reader.
Visibility.
```
gh repo view --json visibility -q .visibility
```
(the gatherer records it too), or the repo's details from a GitHub MCP server when there is no
```
gh
```
. Private or unknown means nothing internal is linked.
House style. The product's exact name (pass it, and any shorthand, to
```
lint.mjs --product "Full Name,Short"
```
) and terms to use or avoid. Read
```
house-style.md
```
in the repo's folder of work dirs first (
```
workdir.mjs
```
prints its path, and says where to create it when there isn't one yet); when the author settles a name or term, add it there so the next run doesn't ask. For a private repo, add names that must not appear (customers, partners, internal codenames). Pass the avoid-list to
```
lint.mjs --avoid
```
; paraphrase around an avoided term, never inside a quotation.
Brand. The product's colours, fonts and logo, kept in
```
brand.json
```
next to
```
house-style.md
```
(
```
workdir.mjs
```
prints its path, or where to create it). When it exists, the post, the motion cut and the deck follow it with no further step:
```
viz.mjs build
```
writes it into the post, and
```
motion.mjs
```
and
```
deck.mjs
```
read it. When it doesn't and the post will live on the product's own site, or the author mentions a brand, ask once for the accent colour, the fonts and a logo file, save them there, and check the file with
```
node <skill-dir>/scripts/brand.mjs --check <path>
```
. Otherwise leave it: the default look needs no file. visuals.md
Modules. Opt-in appendix extras (build log, process numbers, by-day timeline, review notes, how-made, sources), all off by default. Include the ones the author asks for; offer one in a single line only when the evidence makes it unusually good. modules.md
Other repos. If part of the feature shipped elsewhere (a CLI, an SDK), repeat the search there with
```
--search … --also-repo owner/name
```
.

根据请求、repo 和默认值确定以下事项。不要单独询问范围；如果确实不清楚，则在步骤 3 的一条消息中一并询问。

主题。 文章讨论的核心想法。作者指向的任何对象（一个 Issue、几个 PR、一段搜索词、一个 commit 范围、一个路径）都只是线索，不是边界。同一时期附近落地的相关工作（dossier 中的 Nearby work）通常属于同一个想法，而作者指向的内容也可能只有一部分相关。应当围绕想法划定边界。
体裁和篇幅。 真实功能默认采用构建故事；单薄改动采用 note，或得出“不值得写”的结论。如果作者要求技术或工程文章，就采用深度解析：内部机制、Operator 工具和权衡取舍可以成为主题，而面向读者的测试会按 craft.md 和 brief.md 面向该读者调整。
可见性。 运行
```
gh repo view --json visibility -q .visibility
```
（采集器也会记录），或者在没有
```
gh
```
时通过 GitHub MCP server 获取 repo 详情。私有或未知意味着不能链接任何内部内容。
House style。 产品的准确名称（将其及任何简称传给
```
lint.mjs --product "Full Name,Short"
```
）以及需要使用或避免的术语。先读取 work dir 文件夹中的
```
house-style.md
```
（
```
workdir.mjs
```
会打印路径，并在目录不存在时说明应在哪里创建）；当作者确定名称或术语后，将其写入该文件，以免下次运行时再次询问。对于私有 repo，还要加入不得出现的名称（客户、合作伙伴、内部代号）。将避免词列表传给
```
lint.mjs --avoid
```
；改写时绕开避免词，绝不要在引文中使用。
品牌。 产品的颜色、字体和 logo，保存在
```
house-style.md
```
旁的
```
brand.json
```
中（
```
workdir.mjs
```
会打印路径或所在位置）。存在该文件时，文章、动效短片和 deck 会自动遵循，无需额外步骤：
```
viz.mjs build
```
会将其写入文章，
```
motion.mjs
```
和
```
deck.mjs
```
会读取它。如果不存在，但文章将发布在产品自己的站点上，或者作者提到了品牌，则一次性询问强调色、字体和 logo 文件，将其保存并运行
```
node <skill-dir>/scripts/brand.mjs --check <path>
```
检查。否则保持默认，无需文件。visuals.md
Modules。 可选的附录扩展（build log、流程数字、按天划分的时间线、review 笔记、how-made、sources），默认全部关闭。只加入作者要求的模块；只有当证据使某个模块格外出色时，才用一行主动提出。modules.md
其他 repo。 如果功能的一部分发布到了其他地方（CLI、SDK），使用
```
--search … --also-repo owner/name
```
在那里重复搜索。

2. Gather the evidence

2. 收集证据

Make a work dir outside the repo, so it survives worktrees and never lands in tracked files.

<work-dir>

below means this path, or the author's own place if they name one.

<skill-dir>

means the folder this

SKILL.md

was loaded from (for example

~/.claude/skills/buildnotes

~/.agents/skills/buildnotes

~/.config/opencode/skills/buildnotes

bash

WORK=$(node <skill-dir>/scripts/workdir.mjs preview-links)   # → $BUILDNOTES_DIR (default ~/.buildnotes)/<repo>/<date>-preview-links

Run the gatherer (needs

git

and an authenticated

gh

;

--help

lists every flag):

bash

node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --issue 412
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --pr 120,131,140 --download
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --search "rate limit" --also-repo acme/cli
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --since 2026-09-01 --path src/limits   # git only
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --issue 412 --prior "rate limit"     # earlier PRs matching this phrase

It writes

dossier.md

(a skimmable digest) and

dossier.json

(everything). The digest opens with totals, hot files and Story candidates, then Nearby work (other merged PRs within

--window

days, default 2; ★n = files shared with the selected work), Prior work, feedback signals, cross-repo references, a timeline, and each issue and PR. Issues the selected PRs close, or say they are part of ("Part of #12", "Refs #12"), are pulled in automatically; they often hold the problem statement. Since then lists PRs merged after the selected work that touch several of its files: read each before the post says how something behaves today. The digest cuts long bodies at a section break;

gather.mjs --out <work-dir>/evidence --show 2911

prints one PR or issue in full.

--download

keeps each image's own format (often WebP);

sips -s format png in.webp --out in.png

makes a copy any viewer opens. Almost none of this detail goes in the post.

No
gh
? Check with

gh auth status

. The gatherer needs

gh

for issues, PRs, reviews and search, and stops on

--issue

--pr

and

--search

without it (exit 2, one line). Git-only runs still work and read the repo from the

origin

remote. Fall back in this order, and name the source you used in the hand-off:

A GitHub MCP server, if one is connected. Confirm the repo's visibility there, then run the gatherer git-only (
```
--range
```
,
```
--since
```
,
```
--grep
```
,
```
--path
```
) with
```
--visibility public
```
or
```
private
```
, and read the issues, PRs, review comments and linked issues you need through the MCP tools. Nearby work, prior work and "since then" aren't computed for you: list the merged PRs around the span yourself.
Public GitHub pages, as a last resort and only for a public repo. Read the issue and PR pages on github.com like any web page. Long threads fold and some review comments hide, so lean on what the page plainly shows. Never sign in to see more.
Neither. Build from commits alone, and say in the hand-off that the post is thinner for it.

Read

dossier.md

, then the design docs it lists, then code only where a chosen idea lives. Stop when you have the story. evidence.md

在 repo 之外创建 work dir，使其能够跨 worktree 保留，并且绝不会落入受版本控制的文件中。下文的

<work-dir>

指该路径，或作者指定的自己的位置。

<skill-dir>

指加载本

SKILL.md

的文件夹，例如

~/.claude/skills/buildnotes

、

~/.agents/skills/buildnotes

或

~/.config/opencode/skills/buildnotes

。

bash

WORK=$(node <skill-dir>/scripts/workdir.mjs preview-links)   # → $BUILDNOTES_DIR (default ~/.buildnotes)/<repo>/<date>-preview-links

运行采集器（需要

git

和已登录的

gh

；

--help

列出了全部参数）：

bash

node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --issue 412
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --pr 120,131,140 --download
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --search "rate limit" --also-repo acme/cli
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --since 2026-09-01 --path src/limits   # git only
node <skill-dir>/scripts/gather.mjs --out <work-dir>/evidence --issue 412 --prior "rate limit"     # earlier PRs matching this phrase

它会写出

dossier.md

（便于快速浏览的摘要）和

dossier.json

（全部数据）。摘要先列出总数、热点文件和 故事候选（Story candidates），然后是 附近工作（Nearby work）（所选工作前后

--window

天内合并的其他 PR，默认 2 天；★n 表示与所选工作共享的文件数）、此前工作（Prior work）、反馈信号、跨仓库引用、时间线，以及每个 Issue 和 PR。选定 PR 所关闭或声明为其组成部分的 Issue（“Part of #12”“Refs #12”）会被自动拉取；它们通常包含问题陈述。Since then 会列出选定工作之后合并、且触及多个相同文件的 PR：在文章声称功能的当前行为之前，必须逐个阅读。摘要会在分节符处截断长正文；

gather.mjs --out <work-dir>/evidence --show 2911

会完整打印某个 PR 或 Issue。

--download

会保留每张图片的原始格式（通常为 WebP）；

sips -s format png in.webp --out in.png

可生成任意查看器都能打开的副本。这些细节几乎都不会进入文章。

没有
gh
怎么办？先运行

gh auth status

。采集器需要

gh

获取 Issue、PR、review 和搜索结果；没有它时，使用

--issue

、

--pr

或

--search

会停止执行（退出码 2，并输出一行提示）。仅使用 git 的运行仍然可用，并会从

origin

remote 读取 repo。按以下顺序回退，并在交付时说明使用了哪个来源：

GitHub MCP server，如果已连接。先在那里确认 repo 的可见性，再以 git-only 方式运行采集器（
```
--range
```
、
```
--since
```
、
```
--grep
```
、
```
--path
```
），并使用
```
--visibility public
```
或
```
private
```
；通过 MCP 工具阅读所需的 Issue、PR、review 意见和关联 Issue。附近工作、此前工作和“Since then”不会自动计算，需要自行列出相应时间范围内合并的 PR。
公开 GitHub 页面，作为最后手段，且只适用于公开 repo。像阅读普通网页一样阅读 github.com 上的 Issue 和 PR 页面。长对话会被折叠，一些 review 意见也会隐藏，因此应主要采用页面明确展示的信息。绝不能为了查看更多内容而登录。
两者都不可用。 仅根据 commit 构建，并在交付时说明文章因缺少这些材料而更为单薄。

阅读

dossier.md

，然后阅读其中列出的设计文档，最后只在选定的想法所在位置阅读代码。当故事已经完整时停止。evidence.md

3. Frame the story

3. 构建故事框架

Decide which story this is before planning beats. Zoom out to the product as users meet it, earlier releases in the area, and how other tools do the same job. Run the lenses, draft two or three angles, and recommend one. Then write the brief at the top of

plan.md

: headline, starting point, endpoint, prior context, audience, supporting cast and what's out of frame.

Ask as little as possible. Decide what you can infer and mark it assumed. Ask only about a guess that would change the shape of the post (usually the audience, or two angles too close to call): one message, rarely more than two questions, zero is fine. Either way, tell the author the frame in two or three lines and keep going; wait only if you asked. brief.md

在规划 beats 之前，先确定这是哪一类故事。退一步观察用户接触到的产品、该领域更早的发布版本，以及其他工具如何完成同一项工作。应用各个分析视角，起草两到三个 angles，并推荐其中一个。然后在

plan.md

顶部撰写 brief：标题、起点、终点、前置背景、受众、辅助角色，以及不包含在范围内的内容。

尽量少提问。可以推断的内容直接决定，并标记为 assumed。只有当某个猜测会改变文章形态时才询问，通常是受众，或两个角度难以取舍：一次发一条消息，极少超过两个问题，也可以一个问题都不问。无论如何，都用两三句话告诉作者你采用的框架，然后继续执行；只有当你提出问题并需要答案时才等待。brief.md

4. Plan the beats

4. 规划 beats

Under the brief in

plan.md

Thesis. One sentence from the brief's starting point to its endpoint.
Beats. One per chapter, each with the idea, the decision and the alternative if there is one, the evidence, and the takeaway (what the reader understands after it). A beat with no takeaway is cut.
Cuts. What you're leaving out and why. Most of the dossier lands here.
Open questions. At most three: gaps only the author can fill whose answer would change a claim, ordered by impact, each with the claim you left out because of it. A gap that wouldn't change the post isn't a question; it stays in Cuts. craft.md
Notes for the author. At most two, and only things they would act on, such as docs that contradict the shipped feature. evidence.md

Don't stop to ask unless an answer would change the headline or a chapter; both lists go with the draft. Shapes, beats and length: story.md.

在

plan.md

的 brief 下方：

Thesis。 用一句话连接 brief 中的起点与终点。
Beats。 每章一个 beat，分别包含理念、决策及可能存在的备选方案、证据，以及 takeaway（读者在本章结束后理解了什么）。没有 takeaway 的 beat 应删除。
Cuts。 哪些内容被排除，以及原因。dossier 中的大部分内容都属于这里。
Open questions。 最多三个：只有作者能够填补、且答案会改变某个论断的缺口。按影响排序，并分别说明因为该问题而省略了什么论断。不会改变文章的问题不属于这里，而应留在 Cuts 中。craft.md
Notes for the author。 最多两条，而且只写作者会采取行动的事项，例如与已发布功能相矛盾的文档。evidence.md

除非答案会改变标题或某一章，否则不要停下来询问。这两份列表都会随草稿一起交付。结构、beats 和篇幅：story.md。

5. Make the visuals

5. 制作视觉素材

For each beat, decide whether a visual earns its place, and make it before writing the text around it. Most visuals are components: write a small spec in

<work-dir>/viz/

and let

scripts/viz.mjs

draw it (flows, steps, bars, before/after numbers, line charts, tables, strips, the parts of one thing, code and terminal blocks, WebGL shaders; each one with its spec in assets/components.html). Code and terminal blocks are evidence, not visuals. Kinds, spec formats, capture recipes and motion rules: visuals.md.

为每个 beat 判断一张视觉图是否物有所值，并在撰写周围文字之前完成它。大多数视觉图都是组件：在

<work-dir>/viz/

中编写一份小型 spec，再让

scripts/viz.mjs

绘制（流程、步骤、柱状图、前后对比数字、折线图、表格、条带、单一部分拆解、代码和终端块、WebGL shader；每种视觉图在 assets/components.html 中都有对应 spec）。代码和终端块属于证据，不算视觉图。视觉图种类、spec 格式、截图捕获方法和动效规则：visuals.md。

6. Write the page

6. 编写页面

Copy assets/template.html to

<work-dir>/post.html

and replace its example content. Its components are a toolbox: most posts use four or five and delete the rest. Point each

<!-- viz … -->

marker at your own spec and render them all with

node <skill-dir>/scripts/viz.mjs build <work-dir>/post.html

; run it again after editing a spec. Opted-in modules go after the last chapter; generate the data ones with

node <skill-dir>/scripts/module.mjs <build-log|numbers|timeline> <work-dir>/evidence/dossier.json

Pick the style before rendering. Plain (the default) is the base: a white page, figures on plain ground, nothing drawn by hand; a project's

brand.json

restyles it. Field notes (

data-style="field-notes"

on the article) suits a post that explains a concept or shares a discovery: a serif page, figures on a dot grid, flows drawn by hand. Ask only when the author has a house look; otherwise choose, and say which in the hand-off. Both work in light and dark. visuals.md

Beyond the figures, the template has a

finding

(what a chapter found, in one sentence; at most one per chapter), margin notes for asides (

<span class="sidenote">

), and keyed figures that name the parts of a screenshot. story.md, visuals.md

将 assets/template.html 复制到

<work-dir>/post.html

，再替换其中的示例内容。模板中的组件是一套工具箱：多数文章只使用四到五个，其余应删除。将每个

<!-- viz … -->

标记指向自己的 spec，并使用

node <skill-dir>/scripts/viz.mjs build <work-dir>/post.html

渲染全部视觉图；编辑 spec 后再次运行。启用的 modules 放在最后一章之后；使用

node <skill-dir>/scripts/module.mjs <build-log|numbers|timeline> <work-dir>/evidence/dossier.json

生成数据类 module。

渲染前先选择样式。Plain（默认）是基础样式：白色页面，视觉图置于朴素背景上，不使用手绘元素；项目的

brand.json

可以重新设置样式。Field notes（在 article 上设置

data-style="field-notes"

）适合解释概念或分享发现的文章：衬线页面、点阵网格背景、手绘流程。只有当作者有固定 house look 时才询问；否则自行选择，并在交付时说明。两种样式都支持浅色和深色主题。visuals.md

除视觉图外，模板还提供

finding

（用一句话概括一章的发现；每章最多一个）、用于旁注的 margin notes（

<span class="sidenote">

），以及为截图标注组成部分的 keyed figures。story.md visuals.md

7. Check

7. 检查

bash

node <skill-dir>/scripts/lint.mjs <work-dir>/post.html --flavor build --product "Name" --avoid "term one,term two" [--private] [--ste] [--offline]

The linter reports words per chapter, banned and writerly phrasing, process detail against the flavor's budget, every sentence with a number, sentence length and passive voice, scan aids, identifiers in the text, masthead stats, terminal blocks, animated-dot faults, rendered components (stale markers, bars off scale, more than one visual in a chapter), the product name in the title or headings (

--product

), leftover template text, a safety scan and a link check (it opens every link;

--offline

skips it). It exits 1 on a hard failure; with

--private

, any link to the repo's issues, PRs or commits is one. Then do the half it can't:

Detail pass. Apply earn every detail to each paragraph. A linter flag is a prompt to cut, not a count to hit.
Craft pass. Read the title, the dek and the headings alone, against craft.md: about the reader, no self-naming, concrete. Then cut the open questions to the three that would change the post.
Fact pass. Tick each number against the dossier, a file or your own run. Test counts come from running the tests, never from grep. Check every shipped/live claim against the code, the release and the docs; record any gap under Notes for the author. Check what would mislead the reader if it were wrong, not every detail.
Safety pass. Read every safety hit, reread each code and terminal block, and open every image.
Render pass.
```
node <skill-dir>/scripts/render.mjs <work-dir>/post.html
```
renders desktop and phone width, light and dark, saves the screenshots and fails on sideways scroll, clipped code and broken images. Then look at the screenshots once. visuals.md

bash

node <skill-dir>/scripts/lint.mjs <work-dir>/post.html --flavor build --product "Name" --avoid "term one,term two" [--private] [--ste] [--offline]

linter 会报告每章字数、禁用和过度文学化的措辞、相对于体裁预算的流程细节、每个含数字的句子、句长和被动语态、便于扫读的设计、正文中的标识符、报头统计、终端块、动画圆点故障、渲染后的组件（过期标记、柱状图比例错误、一章超过一张视觉图）、标题或章节标题中的产品名（

--product

）、残留的模板文本、安全扫描，以及链接检查（它会打开每个链接；

--offline

会跳过检查）。遇到硬性失败时退出码为 1；使用

--private

时，任何指向 repo 的 Issue、PR 或 commit 的链接都会导致失败。然后完成它无法完成的一半：

Detail pass。 对每一段应用“让每个细节都物有所值”。linter 标记是删除内容的提示，不是需要凑够的数量。
Craft pass。 单独阅读标题、dek 和各章标题，并对照 craft.md：确认它们面向正确读者、没有自报名称、内容具体。然后把 open questions 缩减到真正会改变文章的三条。
Fact pass。 逐一核对每个数字的来源，包括 dossier、文件或你自己的运行结果。测试数量来自实际运行测试，绝不能通过 grep 得出。对照代码、发布版本和文档检查所有关于已发布或当前线上行为的论断；将发现的缺口记录在 Notes for the author 中。重点检查错误后会误导读者的内容，而不是每个细节。
Safety pass。 阅读每一条安全扫描结果，重新阅读每个代码块和终端块，并打开每张图片。
Render pass。 运行
```
node <skill-dir>/scripts/render.mjs <work-dir>/post.html
```
，以桌面和手机宽度、明暗两种主题渲染，保存截图，并因横向滚动、代码被裁切或图片损坏而失败。最后再查看一次截图。visuals.md

8. Publish

8. 发布

Embed the images first, so the page is one self-contained file (an Artifact can't load images from other hosts):

bash

node <skill-dir>/scripts/inline-assets.mjs <work-dir>/post.html > <work-dir>/post.published.html

Publish

post.published.html

as a private Artifact (title = the post's name) when the host has an Artifact tool; otherwise leave it in the work dir and give its absolute path. Hand the author the link or path with the open questions and notes: three questions and two notes at most, one line each. The rest stays in

plan.md

. For their own site, add

--standalone

(doctype and viewport meta) or hand over

post.html

plus

assets/

. The chapters convert cleanly to Markdown/MDX on request.

先嵌入图片，让页面成为单个自包含文件（Artifact 无法加载其他主机上的图片）：

bash

node <skill-dir>/scripts/inline-assets.mjs <work-dir>/post.html > <work-dir>/post.published.html

当宿主提供 Artifact 工具时，将

post.published.html

发布为私有 Artifact（标题设为文章名称）；否则把它留在 work dir 中，并提供绝对路径。向作者交付链接或路径，同时附上 open questions 和 notes：最多三个问题和两条备注，每条一行。其余内容留在

plan.md

中。如果文章要发布到作者自己的站点，添加

--standalone

（包含 doctype 和 viewport meta），或者交付

post.html

及

assets/

。按要求，各章也可以干净地转换为 Markdown/MDX。

9. Motion cut (optional)

9. 动效短片（可选）

A short reel of the post, for people who would rather watch than read: a title, the problem, one scene per idea, and how to try it, in under a minute. Make one when the request opens with

video

or asks for a video, a reel or a quick version (Output); otherwise offer it in one line in the hand-off when the post has two or more visuals that move or compare. Write

<work-dir>/motion.json

from

plan.md

and the finished page (every word, number and screenshot comes from the post), then build and export it:

bash

node <skill-dir>/scripts/motion.mjs <work-dir>/motion.json --check
node <skill-dir>/scripts/motion.mjs <work-dir>/motion.json --mp4 --poster   # → motion.html, export/<story>-motion.mp4, export/<story>-motion.png

Play it once and scrub to the end of each scene before handing it over. Publish

motion.html

as its own private Artifact and give the author the MP4.

--gif --scene <n> --size 720

exports one scene as a short clip, for a README or a thread. Scene kinds, the script format and what the checks catch: motion.md.

Exports are named after the story:

<story>

is the work dir's name without its date, so files dragged out of

export/

still say where they came from. When the author names the files, or the work dir's name wouldn't tell a reader which story a file is from, set

"output": { "name": "…" }

motion.json

(it also takes

theme

size

and

fps

) or pass

--name <slug>

export.mjs

motion.mjs

and

deck.mjs

;

--out

sets one file's whole path.

为更喜欢观看而不是阅读的人制作一段文章短片：包含标题、问题、每个理念一个场景，以及如何尝试，总时长不到一分钟。当请求以

video

开头，或要求视频、reel 或快速版本时制作（Output）；否则，如果文章包含至少两张会动或进行比较的视觉图，在交付时用一行主动提出。根据

plan.md

和完成的页面编写

<work-dir>/motion.json

（每个词、数字和截图都来自文章），然后构建并导出：

bash

node <skill-dir>/scripts/motion.mjs <work-dir>/motion.json --check
node <skill-dir>/scripts/motion.mjs <work-dir>/motion.json --mp4 --poster   # → motion.html, export/<story>-motion.mp4, export/<story>-motion.png

交付前播放一次，并拖动到每个场景的结尾进行检查。将

motion.html

作为独立的私有 Artifact 发布，并把 MP4 交给作者。

--gif --scene <n> --size 720

会把单个场景导出为短片，可用于 README 或帖子串。场景种类、脚本格式和检查项：motion.md。

导出文件以故事命名：

<story>

是 work dir 名称去掉日期后的部分，这样从

export/

拖出的文件仍能说明来源。当作者指定文件名，或 work dir 名称不足以让读者判断故事内容时，在

motion.json

中设置

"output": { "name": "…" }

（它还可接受

theme

、

size

和

fps

），或者向

export.mjs

、

motion.mjs

和

deck.mjs

传入

--name <slug>

；

--out

会设置单个文件的完整路径。

10. Deck (optional)

10. Deck（可选）

The same scene script as slides: one scene to a slide, each playing its motion once and then holding, with a 16:9 PDF for meetings and email. Make one when the request opens with

deck

or asks for slides, a deck or a PDF; otherwise mention it in the hand-off line about the cut.

bash

node <skill-dir>/scripts/deck.mjs <work-dir>/motion.json --pdf   # → deck.html, export/<story>-deck.pdf

Click through every slide forward and back before handing it over. Publish

deck.html

as its own private Artifact and give the author the PDF. Keys, the PDF and what it leaves out: deck.md.

使用同一个场景脚本制作幻灯片：一个场景对应一张幻灯片，每张幻灯片播放一次动效后停留在最后一帧，并提供适合会议和邮件的 16:9 PDF。当请求以

deck

开头，或要求 slides、deck 或 PDF 时制作；否则在交付说明中提及短片时可一并说明。

bash

node <skill-dir>/scripts/deck.mjs <work-dir>/motion.json --pdf   # → deck.html, export/<story>-deck.pdf

交付前向前和向后逐张点击检查。将

deck.html

作为独立的私有 Artifact 发布，并把 PDF 交给作者。按键、PDF 及其省略内容：deck.md。

Files

文件

```
scripts/gather.mjs
```
: evidence dossier from git and GitHub

scripts/workdir.mjs

: a work dir under

$BUILDNOTES_DIR

(default

~/.buildnotes/<repo>/

)

```
scripts/lint.mjs
```
: the mechanical half of the Check step
```
scripts/module.mjs
```
: an opt-in module (build log, numbers, timeline) from the dossier
```
scripts/viz.mjs
```
: visual components rendered from small specs (
```
scripts/viz/
```
, one file per kind)
```
scripts/render.mjs
```
: the render pass: both widths and themes, screenshots, and the fit faults
```
scripts/export.mjs
```
: one figure as PNG, GIF, MP4/WebM or standalone SVG, for slides or another blog (visuals.md)
```
scripts/motion.mjs
```
: the motion cut: checks a scene script, builds the reel page from
```
assets/motion.html
```
, and exports it as MP4, WebM, GIF or a still, whole or one scene at a time
```
scripts/deck.mjs
```
: the deck: the motion script as click-through slides (
```
deck.html
```
) and a 16:9 PDF
```
scripts/brand.mjs
```
: the repo's brand (
```
brand.json
```
): checks it and writes its colours, fonts and logo into a post;
```
motion.mjs
```
,
```
deck.mjs
```
and
```
viz.mjs build
```
apply it themselves
```
scripts/names.mjs
```
: export file names,
```
<story>-<what>.<ext>
```
```
scripts/inline-assets.mjs
```
: embed local images and video (
```
src
```
,
```
poster
```
,
```
srcset
```
) as data URIs and drop authoring comments
```
assets/template.html
```
: page template and component toolbox
```
assets/motion.html
```
: the reel page the motion cut and the deck fill in
```
assets/components.html
```
: every component with its spec; the specs are in
```
assets/specs/
```
```
references/brief.md
```
: angles, the brief, and how little to ask the author
```
references/evidence.md
```
: what to read, what to skip, numbers, terminal blocks, sources that disagree
```
references/story.md
```
: shapes, beats, altitude, references, voice, length
```
references/visuals.md
```
: diagram, motion, screenshot and chart patterns
```
references/modules.md
```
: the opt-in module menu and placement rules
```
references/motion.md
```
: the motion cut: when to make one, choosing scenes, the script, build and export
```
references/deck.md
```
: the deck: slides from the motion script, keys, the PDF, limits
```
references/craft.md
```
: what makes a post read as crafted: titles, naming the product, anti-patterns, the hand-off

```
scripts/gather.mjs
```
：从 git 和 GitHub 收集证据 dossier

scripts/workdir.mjs

：在

$BUILDNOTES_DIR

（默认

~/.buildnotes/<repo>/

）下创建 work dir

```
scripts/lint.mjs
```
：检查步骤中的机械检查部分
```
scripts/module.mjs
```
：根据 dossier 生成可选 module（build log、numbers、timeline）
```
scripts/viz.mjs
```
：根据小型 spec（
```
scripts/viz/
```
，每种一个文件）渲染视觉组件
```
scripts/render.mjs
```
：渲染检查：两种宽度、两种主题、截图和适配故障
```
scripts/export.mjs
```
：将单个视觉图导出为 PNG、GIF、MP4/WebM 或独立 SVG，供幻灯片或其他博客使用 visuals.md
```
scripts/motion.mjs
```
：动效短片：检查场景脚本，根据
```
assets/motion.html
```
构建 reel 页面，并导出为 MP4、WebM、GIF 或静态图，也可只导出单个场景
```
scripts/deck.mjs
```
：deck：把动效脚本制作成可逐页点击的幻灯片（
```
deck.html
```
）和 16:9 PDF
```
scripts/brand.mjs
```
：读取 repo 的品牌配置（
```
brand.json
```
）：检查品牌配置，并将颜色、字体和 logo 写入文章；
```
motion.mjs
```
、
```
deck.mjs
```
和
```
viz.mjs build
```
会自行应用这些配置
```
scripts/names.mjs
```
：导出文件名，
```
<story>-<what>.<ext>
```
```
scripts/inline-assets.mjs
```
：将本地图片和视频（
```
src
```
、
```
poster
```
、
```
srcset
```
）嵌入为 data URI，并删除创作注释
```
assets/template.html
```
：页面模板和组件工具箱
```
assets/motion.html
```
：由动效短片和 deck 填充的 reel 页面
```
assets/components.html
```
：所有组件及其 spec；spec 位于
```
assets/specs/
```
```
references/brief.md
```
：angles、brief，以及如何减少向作者提问
```
references/evidence.md
```
：该读什么、该跳过什么、数字、终端块，以及来源不一致时的处理方式
```
references/story.md
```
：结构、beats、叙事层级、引用、语气和长度
```
references/visuals.md
```
：图示、动效、截图和图表模式
```
references/modules.md
```
：可选 module 菜单及放置规则
```
references/motion.md
```
：何时制作短片、选择场景、脚本、构建和导出
```
references/deck.md
```
：从动效脚本制作幻灯片、快捷键、PDF 和限制
```
references/craft.md
```
：让文章显得精心打磨的方法：标题、命名产品、反模式，以及交付说明