zoen-product-engineering

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Zoen Product Engineering

Zoen产品工程

Run Zoen engineering as one coherent system: discover the right product, preserve the domain language, design deep modules, deliver thin vertical slices, and learn from production without sacrificing auditability or reversal.

将Zoen工程作为一个连贯的系统运行：探索正确的产品方向、保留领域语言、设计深度模块、交付精简的垂直切片，同时在不牺牲可审计性或可回滚性的前提下从生产环境中学习。

Load the doctrine

加载准则

Read references/zoen-doctrine.md at the start of every Zoen product task.

Read references/extreme-programming.md when planning a delivery, choosing practices, implementing, reviewing, releasing, or changing the engineering process.

Load

$builder-ethos

(or read

builder-ethos/SKILL.md

) at the start of every build, review, scope, or multi-model recommendation turn. Boil lakes, search before building, keep the user sovereign. Manual SDLC must load it the same way.

Treat repository

AGENTS.md

CONTEXT.md

CONTEXT-MAP.md

, ADRs, specifications, and current code as newer sources of truth. Surface conflicts instead of silently overriding them.

在每个Zoen产品任务开始时阅读references/zoen-doctrine.md。

在规划交付、选择实践、实施、评审、发布或更改工程流程时，阅读references/extreme-programming.md。

在每次构建、评审、范围界定或多模型推荐环节开始时加载

$builder-ethos

（或阅读

builder-ethos/SKILL.md

）。化繁为简，先搜索再构建，保障用户主导权。手动软件开发生命周期（SDLC）也需遵循同样的加载要求。

将仓库中的

AGENTS.md

、

CONTEXT.md

、

CONTEXT-MAP.md

、ADRs、规范文档以及当前代码视为更新的事实来源。若存在冲突需明确指出，而非静默覆盖。

Non-negotiables

不可协商原则

Optimize for the fastest path to a safe production learning loop.
Own Zoen's ontology and control plane; borrow bounded implementations instead of forking an entire product.
Express product behavior as nouns, links, verbs, policies, and evidence.
Route effectful or risky operations through an Action Gateway with policy evaluation, approval where required, idempotency, and an audit event. Agents do not write directly.
Make every production change observable, testable through a public seam, incrementally deployable, and reversible.
Prefer one working vertical slice over horizontal infrastructure built for hypothetical needs.
Keep prototypes disposable. Reimplement validated behavior test-first before production.
Preserve access minimization, individualized credentials, provenance, retention rules, client-owned export, and incident evidence.

优化路径，以最快速度构建安全的生产环境学习循环。
掌控Zoen的本体与控制平面；优先借鉴有界实现，而非fork整个产品。
以名词、关联、动词、策略和证据来表达产品行为。
所有有影响或高风险的操作需通过Action Gateway路由，包含策略评估、必要的审批、幂等性以及审计事件。Agent不得直接写入数据。
确保每一项生产变更都可观测、可通过公共接口测试、可增量部署且可回滚。
优先交付可运行的垂直切片，而非为假设需求构建横向基础设施。
保持原型的可丢弃性。在投入生产前，需以测试优先的方式重新实现已验证的行为。
坚持最小权限访问、个性化凭证、溯源、保留规则、客户自有数据导出以及事件证据留存。

Choose the flow

选择工作流

Situation	Flow
Repository not configured for the skill set	`$setup-matt-pocock-skills`
Large greenfield effort with unresolved dependencies	`$wayfinder` → `$to-spec`
Product or design decision that fits one conversation	`$grill-with-docs`
External fact blocks a decision	`$research`
Behavior or state cannot be settled on paper	`$prototype` logic branch
Interface or experience must be seen	`$prototype` UI branch
Domain language or durable decision is unclear	`$domain-modeling`
Module seam or interface is unclear	`$codebase-design` → `$design-an-interface`
Architecture health review	`$improve-codebase-architecture`
Settled conversation must become buildable	`$to-spec` → `$to-tickets`
Agent-ready ticket must be delivered	`$implement` , which drives `$tdd` and `$code-review`
Hard bug or regression	`$diagnosing-bugs`
Incoming raw request or issue	`$triage`
Conversational testing session	`$qa`
Merge or rebase conflict	`$resolving-merge-conflicts`
TypeScript package seams need enforcement	`$setup-ts-deep-modules`
Fast local feedback is missing	`$setup-pre-commit`
Context must cross sessions	`$handoff`
A reusable skill is being designed	`$writing-great-skills`

Do not stack every skill onto every task. Invoke the smallest flow that resolves the current uncertainty.

场景	工作流
仓库未配置该技能集	`$setup-matt-pocock-skills`
大型全新项目且依赖关系未明确	`$wayfinder` → `$to-spec`
可通过单次沟通确定的产品或设计决策	`$grill-with-docs`
决策受外部事实阻碍	`$research`
行为或状态无法通过书面确定	`$prototype` 逻辑分支
界面或体验需可视化呈现	`$prototype` UI分支
领域语言或长期决策不清晰	`$domain-modeling`
模块接口或边界不清晰	`$codebase-design` → `$design-an-interface`
架构健康度评审	`$improve-codebase-architecture`
已达成共识的沟通内容需转化为可构建的任务	`$to-spec` → `$to-tickets`
已准备好由Agent处理的工单需交付	`$implement` ，该工作流会驱动 `$tdd` 和 `$code-review`
疑难Bug或回归问题	`$diagnosing-bugs`
原始请求或问题进入	`$triage`
会话式测试环节	`$qa`
合并或变基冲突	`$resolving-merge-conflicts`
需要强制执行TypeScript包边界	`$setup-ts-deep-modules`
缺失快速本地反馈机制	`$setup-pre-commit`
上下文需跨会话传递	`$handoff`
正在设计可复用技能	`$writing-great-skills`

不要在每个任务中堆叠所有技能。调用能解决当前不确定性的最小工作流即可。

Delivery loop

交付循环

1. Orient

1. 定位

Read repository instructions, domain docs, relevant ADRs, the current issue or spec, and recent code history.
Identify the real customer, desired outcome, production evidence, and next irreversible decision.
Confirm that issue-tracker and domain-doc conventions exist. Run
```
$setup-matt-pocock-skills
```
if they do not.
State what is known, what is assumed, and what remains a decision.

阅读仓库说明、领域文档、相关ADRs、当前问题或规范以及近期代码历史。
识别真实客户、期望结果、生产环境证据以及下一个不可逆转的决策点。
确认是否存在问题跟踪器和领域文档的约定。若不存在，运行
```
$setup-matt-pocock-skills
```
。
明确已知信息、假设内容以及待决策事项。

2. Collapse uncertainty

2. 消除不确定性

Use
```
$wayfinder
```
when the route cannot fit in one context window. Resolve decision tickets, not implementation work.
Use
```
$grill-with-docs
```
for human decisions. Ask one question at a time and recommend an answer.
Use
```
$research
```
for facts from primary sources.
Use
```
$prototype
```
for questions that require a runnable or visual answer. Record the verdict and discard the production claim of the prototype code.
Use
```
$domain-modeling
```
continuously when words change. Use ADRs only for surprising, hard-to-reverse trade-offs.

Stop discovery when the next valuable vertical slice and its acceptance evidence are clear.

当路径无法在单个上下文窗口中容纳时，使用
```
$wayfinder
```
。解决决策工单，而非直接处理实现工作。
针对人工决策，使用
```
$grill-with-docs
```
。一次提出一个问题并给出建议答案。
针对来自原始来源的事实，使用
```
$research
```
。
针对需要可运行或可视化答案的问题，使用
```
$prototype
```
。记录结论并放弃原型代码的生产环境使用权限。
当术语发生变化时，持续使用
```
$domain-modeling
```
。仅针对意外、难以回滚的权衡决策使用ADRs。

当明确下一个有价值的垂直切片及其验收证据时，停止探索阶段。

3. Specify a vertical slice

3. 定义垂直切片

Run

$to-spec

. Every production slice must name:

customer and outcome;
story and concrete acceptance examples;
nouns, links, verbs, and evidence affected;
public interface and test seam;
policy, risk class, and approval behavior;
AgentRun and ToolCall evidence when agents participate;
observability and value metric;
data access, tenancy, retention, and export effects;
compatibility, migration or parallel-run plan;
rollback trigger and reversal path;
explicit exclusions.

Run

$to-tickets

only after the slice is coherent. Tickets are tracer bullets that cross the full stack and end in demonstrable behavior. Declare blocking edges; do not create horizontal "build all infrastructure" tickets unless a real slice is blocked by them.

运行

$to-spec

。每个生产切片必须明确：

客户与期望结果；
用户故事及具体验收示例；
受影响的名词、关联、动词和证据；
公共接口与测试边界；
策略、风险等级与审批行为；
当Agent参与时的AgentRun和ToolCall证据；
可观测性与价值指标；
数据访问、租户管理、保留规则及导出影响；
兼容性、迁移或并行运行计划；
回滚触发条件与回滚路径；
明确的排除项。

仅当切片内容连贯后，再运行

$to-tickets

。工单是贯穿全栈的追踪点，最终需呈现可验证的行为。声明阻塞依赖；除非真实切片受其阻碍，否则不要创建“构建所有基础设施”的横向工单。

4. Implement with XP

4. 结合极限编程（XP）实施

Agree the seam and acceptance examples for the ticket.
Run
```
$tdd
```
in red → green → refactor slices.
Keep the smallest useful interface and absorb complexity behind it.
Pair on high-risk decisions. When two humans are unavailable, use a separate navigator or reviewer agent as an approximation and keep the human accountable for product and risk decisions.
Integrate small changes frequently. Prefer a protected mainline with very short-lived branches over long-lived feature branches.
Keep the fast verification loop near ten minutes. Split fast and slow gates if the complete suite exceeds it.
Commit only coherent, green, reversible increments. Do not push, merge, deploy, or mutate external systems unless the user has authorized that action.

就工单的接口和验收示例达成一致。
以红→绿→重构的切片方式运行
```
$tdd
```
。
保持最小可用接口，将复杂性隐藏在接口之后。
针对高风险决策进行结对编程。若无法安排两名人员，可使用独立的导航或评审Agent作为替代，但需由人员对产品和风险决策负责。
频繁集成小幅变更。优先使用受保护的主线分支和生命周期极短的特性分支，而非长期特性分支。
保持快速验证循环在十分钟左右。若完整测试套件耗时超过此时间，拆分快速和慢速验证环节。
仅提交连贯、通过测试、可回滚的增量内容。除非用户授权，否则不得推送、合并、部署或修改外部系统。

5. Review and release

5. 评审与发布

Run

$code-review

against both repository standards and the originating specification.

Before production, verify:

acceptance and regression tests pass;
typecheck, lint, build, and relevant security checks pass;
policy and approval paths fail safely;
writes are idempotent and auditable;
logs contain provenance without leaking sensitive data;
tenant isolation and least privilege hold;
migration can run incrementally or in parallel where risk warrants;
rollback has a tested trigger, owner, and procedure;
dashboards or evidence can show customer and operational outcomes.

Deploy the smallest useful increment. For risky substitutions, present impact, alternatives, cost, timeline, compatibility, parallel operation, and reversal before promotion.

对照仓库标准和原始规范运行

$code-review

。

上线前需验证：

验收测试和回归测试通过；
类型检查、代码 lint、构建及相关安全检查通过；
策略和审批路径在异常情况下能安全失效；
写入操作具备幂等性且可审计；
日志包含溯源信息且未泄露敏感数据；
租户隔离与最小权限原则得到遵守；
迁移可根据风险情况增量运行或并行执行；
回滚具备经过测试的触发条件、负责人及流程；
仪表盘或证据可展示客户与业务运营结果。

部署最小可用的增量内容。对于高风险替换操作，在推广前需说明影响、替代方案、成本、时间线、兼容性、并行运行方式及回滚方案。

6. Learn

6. 复盘学习

Review working software with a real customer at least weekly.
Compare expected and observed value evidence.
Treat incidents and escaped defects as feedback. Run
```
$diagnosing-bugs
```
, add a regression test, and perform root-cause analysis.
Reflect on the process regularly and change one thing at a time.
Preserve slack; drop low-priority scope before compromising quality or sustainable pace.

至少每周与真实客户一起评审可用软件。
对比预期与实际的价值证据。
将事件和逃逸缺陷视为反馈。运行
```
$diagnosing-bugs
```
，添加回归测试并执行根本原因分析。
定期反思流程，每次只调整一个环节。
保留缓冲空间；在影响质量或可持续节奏前，优先剔除低优先级范围。

Definition of done

完成定义

A Zoen slice is done only when:

the customer-visible behavior works;
acceptance evidence exists at the agreed seam;
code and tests communicate the behavior;
policy, approval, audit, provenance, and tenancy behavior are explicit;
production telemetry and value measurement exist;
migration and rollback are credible;
documentation and domain language match the implementation;
no hidden follow-up is required to make the slice safe.

If any item is intentionally deferred, record the reason, owner, trigger, and risk in the issue. Do not call the slice production-ready.

仅当满足以下所有条件时，Zoen切片才算完成：

客户可见的功能正常运行；
在约定的接口处存在验收证据；
代码和测试能清晰传达行为；
策略、审批、审计、溯源及租户行为明确；
存在生产环境遥测与价值度量机制；
迁移与回滚方案可信；
文档与领域语言与实现一致；
无需隐藏后续操作即可确保切片安全。

若任何项被有意推迟，需在问题中记录原因、负责人、触发条件及风险。不得将该切片称为生产就绪。