software-factory
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseA software factory is a system of agents that turns tickets, PRs and schedules into merged code, deployed on remote infrastructure the user chooses. This skill is the language for designing one. Use these terms, and only these, when discussing or whiteboarding a factory; when the user reaches for a word under Avoid, name the canonical term.
**software factory(软件工厂)**是一个由 Agent 构成的系统,它把工单、PR 和计划转化为已合并的代码,并部署到用户选择的远程基础设施上。本 skill 是用于设计此类系统的共享语言。在讨论或绘制 software factory 的设计图时,只使用这里定义的术语;当用户使用 Avoid 项下的词时,应改用规范术语。
Tasks and runs
任务与运行
Task:
A kind of work the factory performs, defined once and run many times: review, explore, implement, ratchet. A task may work on a ticket, a PR, or the codebase as a whole.
Avoid: job, workflow, action, as names for the task. A CI vendor's workflow file and its jobs are where a task is wired up, not the task.
Trigger:
The event that starts a run: a change in the ticket tracker or git host, a clock in the orchestrator, or another run.
Run:
One execution of a task on one runner, from its trigger to its finish, treated as a black box. A run triggers further runs either directly, through logic in the orchestrator, or by changing the ticket tracker or git host. A run never waits for a human: it ends, and the human's later change to the ticket tracker or git host triggers a new run.
Avoid: session
Runner:
The disposable machine a run executes on. Nothing on it survives the run, even when the machine itself is long-lived: a run's only memory of earlier runs is the ticket tracker, the git host and the orchestrator.
Avoid: server, host, box, compute, sandbox
Task(任务):
一种由 software factory 执行的工作类型,定义一次、运行多次,例如 review(审查)、explore(探索)、implement(实现)和 ratchet(渐进收紧)。Task 可以处理一张工单、一个 PR,也可以处理整个代码库。
Avoid:作为 Task 的名称时,避免使用 job、workflow、action。CI 厂商的 workflow 文件及其 jobs 是 Task 的接线位置,而不是 Task 本身。
Trigger(触发器):
启动一次 Run 的事件:Ticket tracker 或 Git host 发生变化、Orchestrator 中的时钟到达,或另一次 Run 触发。
Run(运行):
一个 Task 在一个 Runner 上的一次执行,从触发到结束,全程作为一个黑盒对待。Run 可以通过直接方式、Orchestrator 中的逻辑,或修改 Ticket tracker 或 Git host 来触发后续 Run。Run 绝不会等待人工介入:它会结束,人工之后对 Ticket tracker 或 Git host 的修改会触发新的 Run。
Avoid:session
Runner(运行器):
Run 执行时使用的一次性机器。即使机器本身长期存在,Run 结束后,其上也不会保留任何内容;一次 Run 对更早 Run 的唯一记忆来自 Ticket tracker、Git host 和 Orchestrator。
Avoid:server、host、box、compute、sandbox
Services
服务
Ticket tracker:
Where tickets live, and the factory's human interface: humans schedule work by filing tickets, talk to agents in their comments, and their changes to tickets trigger runs.
Avoid: issue tracker, ticket manager, project board
Ticket source:
Anything outside the factory that creates tickets in the ticket tracker: a feedback button, a monitor, an error tracker, an inbox.
Avoid: data source, trigger source, intake
Git host:
Where branches, PRs and reviews live.
Avoid: code host, forge, repo
Orchestrator:
The component that receives triggers, starts runs on runners, and records which runs are queued, in flight or finished.
Avoid: dispatcher, scheduler, control plane
Observability platform:
Where runners send logs, traces and status, so a human can see what happened inside each run. Optional: the product filling the runner or orchestrator slot often shows enough on its own. A run never decides on it until something writes it into the ticket tracker or git host.
Avoid: observability, logs, monitoring, dashboard
Ticket tracker(工单跟踪器):
工单的存放之处,也是 software factory 的人工交互界面:人们通过提交工单来安排工作,在评论中与 Agent 沟通,而对工单的修改会触发 Run。
Avoid:issue tracker、ticket manager、project board
Ticket source(工单来源):
software factory 外部任何能够在 Ticket tracker 中创建工单的事物,例如反馈按钮、监控器、错误跟踪器或收件箱。
Avoid:data source、trigger source、intake
Git host(Git 托管平台):
分支、PR 和评审的存放之处。
Avoid:code host、forge、repo
Orchestrator(编排器):
接收 Trigger、在 Runner 上启动 Run,并记录哪些 Run 已排队、进行中或已完成的组件。
Avoid:dispatcher、scheduler、control plane
Observability platform(可观测性平台):
Runner 向其发送日志、链路追踪和运行状态,以便人们查看每次 Run 内部发生的事情。此服务是可选的:填充 Runner 或 Orchestrator 槽位的产品通常自身就能提供足够的信息。在有内容被写入 Ticket tracker 或 Git host 之前,Run 不会决定是否采用它。
Avoid:observability、logs、monitoring、dashboard
Designing a factory
设计 software factory
A design has two halves: the services, each a slot filled with a product, and the tasks whose runs move work through them.
Start from the user's problem, not the factory: untriaged tickets, PRs waiting for automated review, a stricter automated check to migrate to, bugs nobody reads. When the user names a problem or doesn't know what to build, read EXAMPLE-TASKS.md for the tasks that solve common ones.
一个设计由两半组成:服务,每个服务都是一个由产品填充的槽位;以及 任务,其 Run 让工作穿过这些服务流动。
从用户的问题出发,而不是从 software factory 出发:尚未分类处理的工单、等待自动审查的 PR、需要迁移以采用更严格自动检查的项目,以及无人查看的 bug。如果用户明确提出问题或不知道该构建什么,请阅读 EXAMPLE-TASKS.md,了解可解决常见问题的 Task。
Start slow
缓慢起步
Every trigger is an accelerator. Accelerators without brakes make a slop cannon. There are three brakes:
- Automated checks: deterministic gates (types, lint, tests) that every run must pass.
- Automated review: a separate run that reads the diff cold against the codebase's standards and the ticket, when there is one.
- Human review: a human reads the PR before it merges; what it catches becomes new automated checks and sharper automated review.
Add one automated trigger at a time, throttled at first (one bug report in ten, a clock once a day), with human review on every PR. Open the throttle as the brakes earn trust, and cap every loop of runs at a few tries before a human.
每个 Trigger 都是一种加速器。没有刹车的加速器会变成粗制滥造的加特林(slop cannon)。制动机制有三种:
- 自动检查:确定性关卡(类型检查、lint、测试),每次 Run 都必须通过。
- 自动审查:一次独立的 Run,在存在工单时,依据代码库标准和工单,在不了解前情的情况下阅读 diff。
- 人工审查:人在 PR 合并前进行审查;人工发现的问题会转化为新的自动检查,并推动自动审查变得更加敏锐。
每次只添加一个自动 Trigger,初期要限制其触发频率(每十个 bug 报告处理一个、每天由定时器触发一次),并对每个 PR 安排人工审查。随着制动机制逐步赢得信任,再逐渐放宽限流;同时,每轮 Run 循环在转交人工前最多尝试几次。
Fill every slot
填满每个槽位
Each service is a slot. One product can fill several slots, and one server can host several services. Three designs, side by side:
| Service | All on GitHub | Linear tickets | Own tracker |
|---|---|---|---|
| Ticket tracker | GitHub Issues | Linear | own app |
| Ticket source | feedback button | feedback button, monitor | feedback button, monitor |
| Git host | GitHub | GitHub | GitHub |
| Orchestrator | GitHub Actions | own server + database | own app |
| Runner | Actions runner | Actions, E2B, Daytona or a VPS | own app, or sandboxes |
| Observability platform | none: Actions run pages suffice | an LLM tracing platform | own app |
When the user is choosing a product for a slot, read that slot's survey to get oriented, then research the current options yourself; each survey groups the options by type and lists the questions that decide the slot:
- TICKET-TRACKERS.md
- GIT-HOSTS.md
- RUNNERS.md
- OBSERVABILITY-PLATFORMS.md
Buy the services and build the tasks: the tasks carry the user's design, the services are generic. Favour an off-the-shelf ticket tracker: it is robust, people already know it, and outside users are easy to let in.
每项服务都是一个槽位。一个产品可以填充多个槽位,一台服务器也可以承载多项服务。下面并列展示了三种设计:
| 服务 | 全部采用 GitHub | Linear 工单 | 自建跟踪器 |
|---|---|---|---|
| Ticket tracker | GitHub Issues | Linear | 自建应用 |
| Ticket source | 反馈按钮 | 反馈按钮、监控器 | 反馈按钮、监控器 |
| Git host | GitHub | GitHub | GitHub |
| Orchestrator | GitHub Actions | 自建服务器 + 数据库 | 自建应用 |
| Runner | Actions runner | Actions、E2B、Daytona 或 VPS | 自建应用或沙箱 |
| Observability platform | 无:Actions 运行页面已足够 | LLM 追踪平台 | 自建应用 |
当用户正在为某个槽位选择产品时,先阅读该槽位对应的调研文档以了解概况,然后自行调研当前的选项;每份调研文档都会按类型对选项进行归类,并列出决定该槽位选择的问题:
- TICKET-TRACKERS.md
- GIT-HOSTS.md
- RUNNERS.md
- OBSERVABILITY-PLATFORMS.md
选定并购买这些服务,然后构建任务:任务承载用户的设计,而服务是通用的。优先采用开箱即用的 Ticket tracker:它稳健可靠,人们已经熟悉它,而且便于让外部用户加入。
Question every task
审视每项任务
For each task, answer:
- What triggers it?
- What does it do, and which services does it read and write?
- What does it trigger next?
- Where does a human re-enter?
- What stops two runs doing the same work?
For each ticket source, answer: what stops it filing the same ticket twice?
A design is finished when every slot names a product (or, for the observability platform, a deliberate none) and every task and ticket source has an answer to every question.
针对每项 Task,回答:
- 是什么触发它?
- 它做什么?读写哪些服务?
- 它接下来会触发什么?
- 人工从哪里重新介入?
- 什么机制阻止两个 Run 执行相同的工作?
针对每个 Ticket source,要回答:什么机制能防止它重复提交同一张工单?
设计完成的标准是:每个槽位都指定了产品(对于 Observability platform,可以明确选择不使用),并且每项 Task 和 Ticket source 都回答了上述所有问题。