Archon Execute 命令指南：让 Agent 按计划文件实现代码的六步执行工作流

Archon Execute 命令指南让 Agent 按计划文件实现代码的六步执行工作流【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon本文档解读 Archon 仓库内置的 Claude Code 自定义命令.claude/commands/execute.md。它定义了 Agent 如何读取一份实现计划Plan文件并逐条落地为代码、同时严格遵循 Archon monorepo 工程规范的完整执行流程。读者将掌握如何调用 Execute 命令、六步执行工作流的具体内容、Archon 的包边界与代码风格约束以及通过bun run validate全量校验把变更安全交付的验证体系。Execute 命令是什么.claude/commands/execute.md是 Archon 仓库为 Claude Code及其兼容 Agent提供的 slash command 模板。它通过 frontmatter 声明了命令元数据--- description: Execute an Archon implementation plan file argument-hint: path-to-plan.md ---description命令在候选列表中的展示描述说明该命令用于执行一份 Archon 实现计划文件argument-hint提示调用方需要传入的参数形式——一份计划文件的路径即$ARGUMENTS占位符在实际调用时被替换为path/to/plan.md。该命令与仓库内.claude/commands/下的plan-feature.md计划生成、validate.md验证、handoff.md交接等命令构成一套闭环先规划、再执行、后验证、终交接。Execute 正是其中把计划变成代码的核心环节同时它是一份与 Agent 实现细节解耦的通用模板——仓库外的其他 Claude Code 项目也可以直接复用其骨架。Step 1通读整个计划先建立全局视图Execute 的第一步明确要求在写出第一行代码之前从开头到结尾完整读取$ARGUMENTS指向的计划文件并理解四个要点所有任务及其依赖关系Depends on:排序受影响的包与文件架构注意事项与被禁止的模式prohibited patterns计划末尾的验证步骤。这条约束与 Archon 自身的架构规模直接相关。仓库采用 bun workspaces 管理packages/*下的多个独立包core、git、paths、workflows、providers、isolation、cli等改动往往跨包联动Agent 若在未建立全局视图的情况下动手极易破坏 package.json 中定义的包依赖边界。Step 2验证当前状态确认工作树干净实施前先确认工作区状态避免把无关的未提交改动混入本次交付git status若存在与本计划无关的未提交改动应先行标记提示再继续随后确认当前分支git branch --show-current这一先检查再动手的纪律与 Archon 中 git 操作的基础设施一脉相承。仓库将 git 调用收敛在archon/git包中例如 exec.ts 里的execFileAsync统一包装child_process.execFile并把windowsHide默认设为true避免 Windows 上分离运行--detach的 workflow 每次调用 git 都弹出终端窗口。理解这一点有助于 Agent 在执行计划时同样调用 git 之前先想清楚状态。Step 3按依赖顺序执行任务逐个按计划顺序处理任务严格执行Depends on:排序。每个任务遵循固定的三步循环先读后改修改目标文件之前必须先读取绝不盲目编辑实现使用编辑/写入工具完成变更立即验证改动 TypeScript 文件后立刻编译检查不让类型错误累积bun run type-check 21 | tail -20Archon 代码规范详解Execute 命令内嵌了一套 Archon 仓库的强制代码规范以下结合源码逐一拆解其底层依据。导入规范// Type-only imports import type { IPlatformAdapter, Conversation } from archon/core; // Value imports — named, not namespace import { handleMessage, pool } from archon/core; // Submodule namespace imports (acceptable) import * as git from archon/git;类型导入必须显式import type值导入使用具名导入而非import * as。这套约定与仓库type-check脚本的严格性配套——package.json 中的type-check会对所有 workspace 包逐一执行bun --filter * type-check并额外对scripts/等目录做tsc --noEmit检查任何隐式 any 或未用的类型导入都会在此被拦下。函数规范// All functions need explicit return types async function createSession(id: string): PromiseSession { ... } // No implicit any所有函数必须显式标注返回类型、禁止隐式any。这与仓库各包如 packages/git/src/types.ts中随处可见的显式类型标注风格一致也与lint --max-warnings 0的零警告策略形成双保险。日志规范import { createLogger } from archon/paths; // Lazy logger pattern (test mocks work correctly) let cachedLog: ReturnTypetypeof createLogger | undefined; function getLog(): ReturnTypetypeof createLogger { if (!cachedLog) cachedLog createLogger(my-module); return cachedLog; } // Event naming: {domain}.{action}_{state} log.info({ id }, session.create_started);createLogger由archon/paths包提供其实现位于 packages/paths/src/logger.ts基于 Pino 构建根 logger再以rootLogger.child({ module })创建带模块绑定的子 logger。事件命名采用{domain}.{action}_{state}三段式如session.create_started与logger.ts头部注释中的示例session_started语义一致——实际命名风格以当前命令模板的{domain}.{action}_{state}为准即领域、动作、状态之间用点和下划线区分。关于懒加载模式logger 通常在模块顶层创建但若模块在测试中需要被mock.module()替换顶层初始化会破坏 mock 生效时机因此规范要求将 logger 的创建推迟到首次使用时。错误处理规范// Never swallow errors silently try { await riskyOperation(); } catch (error) { const err error as Error; log.error({ err, context }, operation.failed); throw err; // re-throw or classify for user }禁止静默吞掉异常捕获后必须记录结构化日志携带err与上下文并重新抛出或转化为面向用户的分类错误。这与archon/core中error-formatter、error等工具模块的职责错误分类与格式化输出相呼应。Git 操作规范调用 git 一律使用execFileAsync而非exec禁止执行git clean -fd改用git checkout .恢复工作区使用品牌类型branded typestoRepoPath()、toBranchName()、toWorktreePath()。前两条的源码依据均在 packages/git/src/exec.tsexecFileAsync包装器中第三条的品牌类型定义在 packages/git/src/types.ts通过unique symbol声明RepoPath、BranchName、WorktreePath三种字符串子类型构造函数对空字符串直接抛错从而在类型层面杜绝把普通字符串当仓库路径/分支名/工作树路径的常见错误。这正是可确定的工程规范在类型系统上的落地。包边界约束archon/workflows不得导入archon/corearchon/git不得导入archon/core或archon/workflowsarchon/paths对archon/*零依赖。这一约束与实际依赖声明完全吻合可直接在源码中验证查看各包 package.json 的dependencies字段——archon/paths仅依赖dotenv、pino、pino-pretty、posthog-node等外部包没有任何archon/*内部依赖archon/git只依赖archon/pathsarchon/workflows依赖archon/git、archon/paths、archon/providers但不依赖archon/core。而archon/core作为最上层的聚合包反过来依赖git、isolation、paths、providers、workflows全部下层包。这种单向依赖链保证了核心包不会反向依赖工作流层是 monorepo 架构稳定性的基石。测试规范如新增测试先查目标文件属于包package.json中的哪个测试批次test batchmock.module()在 Bun 中是永久性的新测试文件要放置在合适位置避免污染其他文件的执行对于其他测试文件也会直接使用的模块改用spyOn()而不是mock.module()。仓库各包的package.json中确实存在testGroups字段例如 packages/git/package.json 与 packages/core/package.json 都按文件列表划分了测试批次——这就是查测试批次的落点。仓库根 package.json 还声明了 Bun 运行时版本约束bun: 1.4.2mock.module()的永久语义是 Bun 运行时特有的行为跨版本迁移时需特别留意。Step 4包级增量验证完成某个包的全部任务后先对该包运行验证全部通过再进入下一个包组# Type checking across all packages bun run type-check # Lint (zero warnings policy) bun run lint # Format check bun run format:check # Tests (per-package isolation — do NOT run from repo root directly) bun run test需要特别说明两点bun run test不能从仓库根直接运行根目录的test脚本是bun run scripts/repo-tests.ts它会按包逐一编排测试这也是testGroups存在的意义。规范要求按包隔离运行避免mock.module()的永久性副作用跨测试文件泄漏。lint 遵循零警告策略根目录lint脚本还会先执行check-test-cleanup-drift与lint.ts对测试清理漂移与代码风格一并把关。Step 5全量验证所有任务完成后运行全量验证套件bun run validate文档说明该命令执行type-check lint --max-warnings 0 format:check test四项四项必须全部通过。查看根目录 package.json 中validate脚本的实际定义它比文档描述的链条更完整check:cli-import-boundary check:bundled check:bundled-skill check:bundled-schema check:pi-vendor-map check:capability-matrix check:api-types type-check lint --max-warnings 0 format:check test:install test除了文档明示的四项之外validate还会执行check:cli-import-boundaryCLI 导入边界检查、check:bundled*内置默认值/技能/数据库 schema 的生成物一致性检查、check:pi-vendor-map、check:capability-matrix、check:api-types服务端 API 类型与生成声明的同步性以及test:install安装脚本冒烟测试。因此在实际仓库中运行bun run validate时任一项失败都意味着某处生成物与源码不同步需要先修复再报告完成。Step 6输出结构化完成报告执行收尾阶段必须输出固定格式的报告包含以下部分Tasks Completed以- [x]复选框列出每个任务及改动文件Files Created / Files Modified区分新建与修改给出packages/{pkg}/src/{file}.ts — {purpose}格式的清单Validation Results逐项列出type-check、lint含警告数、format:check、tests含通过/失败数以及全量bun run validate的结果Manual Verification附上可用于人工验证功能的 curl 命令或 UI 操作步骤Notes记录与计划的偏差、意外发现与后续待办。报告模板原文如下可直接作为交付模板## Execution Report: {Plan Name} ### Tasks Completed - [x] Task 1: {description} — {files changed} - [x] Task 2: {description} — {files changed} ... ### Files Created - packages/{pkg}/src/{file}.ts — {purpose} ### Files Modified - packages/{pkg}/src/{file}.ts — {what changed} ### Validation Results - type-check: PASS / FAIL - lint: PASS / FAIL (N warnings) - format:check: PASS / FAIL - tests: PASS / FAIL (N passed, N failed) - Full bun run validate: PASS / FAIL ### Manual Verification {Any curl commands or UI steps to manually verify the feature works.} ### Notes {Any deviations from the plan, unexpected findings, or follow-up work needed.}总结Execute 命令的工程价值Execute 命令把AI 实现代码从不可控的对话过程收敛为一条可复现、可审计、可验证的流水线通读计划 → 校验状态 → 依序实现 → 增量验证 → 全量验证 → 结构化汇报。它与仓库中archon/git的execFileAsync、品牌类型archon/paths的createLogger以及根 package.json 的validate脚本形成完整的证据链——模板中的每一条规范都不是空泛的口号而是可以直接在源码与配置中核实、可执行、可自动校验的工程约束。对于希望在自己仓库中复刻这套确定性 AI 编码工作流的团队这份命令模板连同仓库源码本身就是一份最佳实践标本。【免费下载链接】ArchonThe first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.项目地址: https://gitcode.com/GitHub_Trending/archon3/Archon创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考