设计开发自动化基础架构的 software-factory 技能使用指南
機械翻訳 / Machine-translated
機械翻訳 / Machine-translated
原文链接：设计开发自动化基础架构的 software-factory 技能使用指南（cccskills）
技能页面：software-factory
本文结论
software-factory 是一款技能，用于以统一术语设计"将工单到合并全流程委托给 Agent"的机制。
引入后，开发负责人和个人开发者可以按照固定术语和问题逐步细化设计。
本文将依次介绍可统一的术语与服务配置、安装方法、请求示例，以及使用前需要了解的注意事项。
使用 software-factory 后，可以用固定术语和固定问题来细化开发自动化设计。
这里所说的"软件工厂"，是指以工单、PR 或定时执行为触发，由 Agent 运行并最终产出已合并代码的机制。
例如，可以这样请求：
请使用 software-factory，设计一个用于对未分类工单进行归类的软件工厂。
工单使用 GitHub Issues 管理。
Agent 会先从想解决的问题切入，而不是先描述机制的全貌。
对于未分类工单之类的常见问题，可参考附带的 EXAMPLE-TASKS.md 中对应的任务示例。
设计分为"服务"和"任务"两部分。
服务层面，需要为工单管理、Git 托管等每个槽位选定产品。
任务层面，需要回答触发条件、人工确认节点等五个问题。
所有槽位填入产品、所有问题给出答案后，设计即告完成。
在对话过程中，如果说到"job"或"workflow"，Agent 会指出正式术语应为"task"。
因此，团队内部可以在用词统一的前提下推进讨论。
该技能的核心是设计中使用的九个术语。
Agent 只使用这些术语，遇到应避免的说法时会进行替换。
| 术语 | 含义 |
|---|---|
| Task（任务） | 一次定义、多次执行的工作类型，如评审、调研、实现等 |
| Trigger（触发器） | 启动 Run 的契机，如工单管理或 Git 托管的变更、时间点、其他 Run |
| Run（运行） | 在单台 Runner 上执行一次 Task 的单次运行 |
| Runner（运行器） | Run 所在的一次性环境，结束后不留任何状态 |
| Ticket tracker（工单管理） | 工单的存放位置，是人与 Agent 的交互窗口 |
| Ticket source（工单来源） | 反馈按钮、监控、错误追踪器、收件箱等 |
| Git host（Git 托管） | 分支、PR、评审的存放位置 |
| Orchestrator（编排器） | 接收触发器并启动 Run，记录等待中、执行中、已完成状态 |
| Observability platform（可观测性平台） | 供人查看 Run 日志和状态的地方，可以没有 |
设计的前提假设也已明确。
其一，Run 不等待人工回复，直接结束。
当人修改工单或 PR 时，新的 Run 才会启动。
其二，Runner 不保留上次的记忆。
因此，历史上下文仅保存在工单管理、Git 托管和编排器中。
增加触发器越多，自动化速度越快，但若没有约束，低质量的变更就会大量产生。
为此，需要内置以下三个"刹车"：
| 刹车 | 内容 |
|---|---|
| 自动检查 | 类型检查、lint、测试等，所有 Run 必须通过的固定关卡 |
| 自动评审 | 由另一个 Run 无偏见地阅读差异，与规范和工单进行对照 |
| 人工评审 | 合并前由人阅读 PR，发现的问题反馈至自动检查和自动评审中 |
自动触发器每次只增加一个，初期严格控制数量。
例如：每十个 bug 报告只处理一个，定时执行每天一次。
同时，初期所有 PR 均由人工确认。
Run 的循环次数也需设置上限，超过几次后交还给人工处理。
每个服务作为填入产品的槽位来处理。
一款产品可以填入多个槽位。
技能中列举了以下三种配置示例：
| 服务 | 全部使用 GitHub | 工单使用 Linear | 自建 Tracker |
|---|---|---|---|
| 工单管理 | GitHub Issues | Linear | 自建应用 |
| 工单来源 | 反馈按钮 | 反馈按钮、监控 | 反馈按钮、监控 |
| Git 托管 | GitHub | GitHub | GitHub |
| 编排器 | GitHub Actions | 自建服务器与数据库 | 自建应用 |
| 运行器 | Actions Runner | Actions、E2B、Daytona、VPS | 自建应用或沙盒 |
| 可观测性平台 | 无（Actions 执行界面已足够） | LLM 追踪工具 | 自建应用 |
基本原则是"服务购买现成品，任务自行构建"。
设计的精髓体现在任务中，服务使用通用产品即可。
工单管理推荐使用现成产品。
原因在于：现成产品稳定可靠，使用者已熟悉操作方式，也便于邀请外部人员加入。
针对每个任务，需要回答以下五个问题：
对于工单来源，还需要回答防止同一工单被重复创建的机制。
请在终端执行以下命令。
过程中可以选择安装到 Claude Code 或 Codex 等目标环境。
npx skills add https://github.com/mattpocock/skills --skill software-factory
如果希望让 Agent 来完成安装，请直接发送以下内容：
次の Agent Skill をインストールしてください。
https://github.com/mattpocock/skills/tree/main/skills/in-progress/software-factory
まず SKILL.md と付属ファイルの中身を確認し、不審な処理（外部への送信、認証情報の読み取りなど）がないことを確かめてから、Claude Code なら ~/.claude/skills/software-factory/、Codex なら ~/.agents/skills/software-factory/ に配置してください。
安装位置根据是否在所有项目中使用来选择：
| 安装目标 | 在所有项目中使用 | 仅在特定项目中使用 |
|---|---|---|
| Claude Code | ~/.claude/skills/ | 项目的 .claude/skills/ |
| Codex | ~/.agents/skills/ | 项目的 .agents/skills/ |
该技能配置为不由 Agent 自行判断加载。
使用时，请在请求中指定技能名称，或在 Claude Code 中通过 /software-factory 调用。
第一个示例：尚不确定从何处开始自动化时的咨询。
请使用 software-factory，设计一个解决 PR 评审积压问题的工厂。
希望从保留人工评审的方式开始。
Agent 会从 EXAMPLE-TASKS.md 中选取合适的任务，依次填写服务槽位和每个任务的五个问题。
初始触发器限定为一个，并在答案中说明人工确认节点。
第二个示例：关于产品选型的咨询。
请使用 software-factory，帮我决定运行器使用什么。
请对比 GitHub Actions 和外部沙盒。
Agent 会先阅读附带的 RUNNERS.md 了解全貌，然后重新调研当前的可选项。
调研资料将选项按类别分类，并列出用于决策的问题。
返回结果将按照这些问题进行对比分析。
第三个示例：深化单个任务的请求。
请使用 software-factory，整理 PR 自动评审任务的触发条件、读写的服务、接下来触发的内容、人工确认节点，以及防止重复执行的方式。
将返回按五个问题逐一作答的整理结果。
无法给出答案的项目，将作为设计中的待定事项保留。
software-factory 是用于整理设计的技能。
包含的文件仅有 SKILL.md 和五份 Markdown 参考资料，不包含用于运行自动化的脚本。
GitHub Actions 的配置和运行器的搭建，需要在设计确定后另行推进。
附带调研资料中的产品信息，仅作为了解全貌的参考线索。
SKILL.md 中明确说明，当前可选项应由 Agent 自行重新调研。
产品功能和定价，请在决策前查阅官方信息加以确认。
该技能存放于仓库的 in-progress 文件夹中，许可证为 MIT。
安装前和更新后，建议阅读 SKILL.md 及附带文件的内容，以确保放心使用。
同一个 mattpocock/skills 仓库中，还有可在设计前后使用的其他技能。
code-review 是将规范符合性与需求实现分开进行变更评审的技能。
在考虑自动评审任务时可作参考。
domain-modeling 是整理项目业务术语和概念边界，并记录到术语表中的技能。
如果不知道从哪个技能入手，可以向 ask-matt 咨询。
ask-matt 会根据实际情况推荐合适的技能和使用顺序。
该技能涵盖的是设计层面的术语和思路，不包含搭建步骤或脚本。
能提供帮助的范围，仅限于确定使用哪些服务、由什么触发哪些任务。
可以。
其中一种配置示例就是：工单管理使用 GitHub Issues，编排器使用 GitHub Actions，运行器使用 Actions Runner。
这种配置下，Actions 执行界面已经足够，因此不设置可观测性平台。
请直接说明想解决的问题。
如果存在未分类的工单、等待自动评审的 PR、无人查看的 bug 报告等情况，Agent 会从 EXAMPLE-TASKS.md 中给出对应的任务示例。
前提是内置自动检查、自动评审、人工评审三个刹车。
触发器每次只增加一个，从所有 PR 均由人工确认的阶段开始。
在确认刹车机制可信赖之后，再逐步放宽限制。
software-factory 是一款技能，用于以统一术语设计"将工单到合并全流程委托给 Agent"的机制。
适合团队内部叫法尚未统一的开发负责人，以及从零开始规划配置的个人开发者。
首先整理的是想解决的问题，以及承担该问题的第一个任务所对应的五个问题。
在此基础上，逐一确定各槽位的产品，并逐步增加触发器。
安装方法和概览已汇总在 cccskills 页面。
仓库地址：https://github.com/mattpocock/skills/tree/main/skills/in-progress/software-factory
本文转载自 cccskills 的文章「设计开发自动化基础架构的 software-factory 技能使用指南」。
技能详情与安装方法请参见 cccskills 的 software-factory 页面。