试着给 dev-orchestra 的每个角色交代固定的指示

前言

每次给 dev-orchestra 提需求，我都会写同样的要求，比如“测试用 python -m unittest 跑”“只用标准库写”。用上 1.2.1 加入的 instructions，这类固定的指示就可以按角色只写一次。从 v1.1.0 到 v1.2.1 的全部变化，整理在发布文章（英文）里。

上一篇试了如何把 dev-orchestra 更新到新版本。

试用的环境如下。

• Windows 11
• dev-orchestra 1.2.1
• Claude Code 2.1.309（implementer 是 Claude 的 sonnet）
• Codex CLI 0.163.0（审查者之一）

试用时，我把 DEV_ORCHESTRA_HOME 指向一个与平时配置分开的文件夹，并在专门建的小型 Python 仓库（textkit）里运行。编排器平时会自动推进的步骤，这里我用命令逐一执行。

dev-orchestra 已在 GitHub 开源（MIT 许可证）。如果觉得有用，给个 Star 我会很高兴。

→ github.com/istb16/dev-orchestra

步骤

1. 写指示

在仓库的 .dev-orchestra.yaml 中写上 instructions。

version: 1
instructions:
  orchestrator: "Ask before adding a new dependency."
  implementer:
    file: .dev-orchestra/implementer.md
  reviewers: "Check that every public function in textkit/ has a docstring."

给 implementer 的指示看起来会越写越长，所以我把它单独放进了一个文件。

- Use only the Python standard library.
- Every public function gets a docstring and type hints.
- Run tests with `python -m unittest`.

可以写指示的角色如下。

键	交给谁
orchestrator	编排器（Claude Code 等推进工作流的一方）
architect	写计划的角色
implementer	负责实现的角色
review_fixer	修复审查意见的角色
reviewers	所有代码审查者
design_reviewers	所有设计审查者

值是字符串或 {file: <路径>}。路径是相对于仓库根目录的相对路径，不能指向仓库之外。审查者的席位上，也可以写只针对该席位的 instructions。

2. 阅读 config validate 的提醒

写好之后运行 config validate。

$ dev-orchestra config validate
Configuration is valid.
Warnings:
  - instructions.orchestrator: the project config (.dev-orchestra.yaml) gives the session standing orders, which `status` tells it to follow; that file can come with the branch under review, so check that this is intended
  - instructions.implementer: the project config (.dev-orchestra.yaml) gives the implementer standing orders, and it runs with write access; that file can come with the branch under review, so check that this is intended
  - instructions.reviewers: the project config (.dev-orchestra.yaml) sets reviewer instructions; that file can come with the branch under review, so check that this is intended

配置本身是正确的，但每条指示都会出现一行提醒。这是因为仓库里的 .dev-orchestra.yaml 有可能随着被审查的分支一起进来。如果别人的分支里写着“implementer 要这样做”，它就会被交给一次拥有写权限的运行。implementer 那一行写着 it runs with write access，就是这个原因。

提醒并不是拒绝。如果是自己写的指示，照常继续就行。同样的几行在 doctor 和 review run 中也会出现。

3. 用 status 和 config show 确认

status 会显示 Instructions: 一行。从中可以看出，哪些角色有指示生效、来自哪里（global 还是 project，内联还是文件），以及有多少个字符。

$ dev-orchestra status
...
Plan approval: pending -- present .ai/workflows/instr/plan.md and the instructions in force to the user and ask; a yes is recorded with `design approve`, never without one
Instructions: orchestrator (project, inline, 35 chars); implementer (project, .dev-orchestra/implementer.md, 135 chars); reviewers (project, inline, 61 chars)
Orchestrator instruction (follow it; the skill's rules come first):
  Ask before adding a new dependency.

要点有两个。

• 给编排器的指示不是通过提示词，而是通过 status 传达的。 编排器一边读 status 一边推进，所以正文会原样显示，并附上“skill 的规则优先”
• 请求批准计划时，会被提示把指示也一并展示。 只要有指示生效，Plan approval: 一行就会加上 and the instructions in force

config show 中也会出现 Instructions 一节。

  Instructions
    orchestrator (project, inline, 35 chars)
    implementer (project, .dev-orchestra/implementer.md, 135 chars)
    reviewers (project, inline, 61 chars)
    Orchestrator instruction:
      Ask before adding a new dependency.

4. 查看 implementer 收到的提示词

我批准了一个小计划（添加 truncate(text, width)），然后运行了 implementer。为了看到提示词，我又把 implementer 切换到 mock 适配器（不消耗 token 的测试用适配器），用 --detach 再运行一次，打开了保存下来的提示词。

## Project instructions

Where a project instruction conflicts with any other rule in this prompt or with the request below, follow those instead.
Sources: project .dev-orchestra/implementer.md.

- Use only the Python standard library.
- Every public function gets a docstring and type hints.
- Run tests with `python -m unittest`.

Implement the approved plan at .ai/workflows/instr/plan.md.
...

指示放在 ## Project instructions 标题下，位于需求之前。由于附有一行“与其他规则或需求冲突时，以那些为准”，指示的分量比 CLI 的规则和需求要弱。

用 Claude（sonnet）运行时写出的 textkit/truncate.py，按照指示带有类型提示和 docstring，并且只用了标准库。

def truncate(text: str, width: int) -> str:
    """Return text unchanged if it fits in width, else cut it so that the result ending in "..." is width characters long.

    Raises ValueError if text must be cut but width is too small to hold "...".
    """

计划里既没写类型提示，也没写 docstring。我认为它们之所以出现是指示的功劳，但我并没有在没有指示的情况下运行同一个计划来做对比。

5. global 和 project 的指示会拼接起来

instructions 的行为与其他设置不同。其他键是 project 的值覆盖 global 的值，而 instructions 会把两边的正文拼接起来（global 在前）。

我在 global 配置（DEV_ORCHESTRA_HOME 中的 config.yaml）里也加了一条给 implementer 的指示。

instructions:
  implementer: "Keep each change small; leave no TODO comments."

status 中会并列出现两条 implementer 的指示。

Instructions: orchestrator (project, inline, 35 chars); implementer (global, inline, 47 chars); implementer (project, .dev-orchestra/implementer.md, 135 chars); reviewers (project, inline, 61 chars)

自己的偏好（global）和仓库的规矩（project）可以分开写。

6. 给审查者的指示只能“增加要看的内容”

给审查者的指示放在任务规则之后、变更之前。此外，审查者会被告知指示只能增加要看的内容。像“不要提这条意见”“把 severity 调低”这样的指示，审查者不会照做。这是为了防止随分支一起进来的指示让审查变得宽松。

审查者的提示词不会保存到文件里，所以我用 mock 适配器上的审查者来确认。mock 在提示词中包含环境变量 DEV_ORCHESTRA_MOCK_FAIL 里写的字符串时会失败。我用这种方法确认了指示的正文（has a docstring）和“只能增加要看的内容”那句话（may only add）都在审查者的提示词中（换成提示词里没有的字符串时则成功）。

7. 修改指示的变更会作为高风险来审查

我把一个改写了指示文件的变更拿去审查。

$ echo "- Never edit tests/ without a failing test first." >> .dev-orchestra/implementer.md
$ dev-orchestra review run --force
note: balanced → quality: .dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)
note: claude-test (when: relevance) added: .dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)
note: high-risk round (.dev-orchestra/implementer.md matches .dev-orchestra/implementer.md (and 1 more)): claude-security runs opus instead of sonnet
ok      claude-general     claude   opus               1 finding(s)
ok      codex-general      codex    gpt-6.1-sol        0 finding(s)
ok      claude-security    claude   opus               0 finding(s)
ok      claude-test        claude   sonnet             2 finding(s)
ok      mock-general       mock     recommended-coding 0 finding(s)

5 successful, 0 failed

（省略了 instructions 的提醒行。mock-general 是步骤 6 中加的测试用审查者。加上 --force，是因为在同一项工作中已经跑了好几次审查，需要越过次数上限（2 次）。）

虽然只改了一行，但优化级别从 balanced 升到了 quality，整个审查组都运行了，安全审查者也升级到了 opus。review snapshot --json 中也会把改动过的指示文件记录为 instruction_changes。

{'instruction_changes': ['.dev-orchestra/implementer.md']}

指示会作用于此后的每一次运行。所以，修改指示的变更会和认证、支付相关的代码一样，被当作高风险对待。

8. 指示文件不存在时

我试着删掉指示文件，status 显示 0 chars: not found，doctor 则给出了一条 note。

Instructions: orchestrator (project, inline, 35 chars); implementer (global, inline, 47 chars); implementer (project, .dev-orchestra/implementer.md, 0 chars: not found); reviewers (project, inline, 61 chars)

  - instructions for implementer (project file): .dev-orchestra/implementer.md not found; runs go on without it

运行不会停止，而是在没有这条指示的情况下继续。 根据参考文档，文件大于 32 KB，或经由链接、junction 访问时，也是同样的处理（这些我没有试）。

9. 面向工作单元的设置也一起加入了

1.2.1 还新增了两个面向工作单元（1.2.0）的设置。

设置	内容
implementation.unit_tests: after_merge	各工作单元不跑测试，全部合并之后只跑一次。适用于测试共用数据库或端口的情况
implementation.worktree_files	把 git 忽略的文件（config/database.yml、.env.test 等）复制到工作单元的 worktree 中

unit_tests: after_merge 我在工作单元的文章里用过。worktree_files 这次没有试。

总结

• 可以在 .dev-orchestra.yaml（或 global 配置）的 instructions 中，按角色写固定的指示。内联或写在文件里都可以
• 对于 project 文件中的指示，config validate / doctor / review run 会每条给出一行提醒，因为它们可能随分支一起进来
• 指示放在提示词中的 ## Project instructions 下，分量比 CLI 的规则和需求弱。给编排器的指示显示在 status 中
• global 和 project 的指示会拼接起来（不像其他设置那样覆盖）
• 给审查者的指示只能增加要看的内容，不能让审查者少提意见
• 修改指示的变更会作为高风险来审查
• 即使指示文件不存在，运行也不会停止

下一篇把计划拆分成工作单元，并行地实现。

GitHub： istb16/dev-orchestra（给个 Star 会是很大的鼓励）

本系列的文章可以在“dev-orchestra”文章列表中集中阅读。