在 Amazon Q Developer CLI 上落地 Loop Engineering调度、规则、状态与 Maker/Checker 拆分的完整迁移指南【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineeringAmazon Q Developer CLIq chat是一个 AWS 原生的终端 Agent可充当 AI 编码循环Loop的宿主环境。本文基于 loop-engineering 仓库为 docs/primitives-matrix.md 新增的Amazon Q 附录其来源是 scripts/issue-bodies/amazon-q-appendix.md 这张 good-first-issue系统讲解如何把「调度、规则/上下文文件、STATE.md状态、Maker/Checker 检核拆分、MCP 连接器」等循环原语映射到q chat上。读完本文你将拿到一份可直接复制的第一周 Daily Triage 只读提示词、一套自定义 Agent 配置daily-triage.json与loop-verifier.json以及明确的「诚实缺口」清单——知道哪些能力在 Q 中还不是一等公民并据此设计出工具无关、可持续迁移的循环系统。从一张 Issue 到一份附录本文的由来与定位在进入技术细节前先说明本文内容的出处与坐标系。仓库的社区协作脚本 scripts/create-good-first-issues.sh 会按scripts/issue-bodies/下的模板批量生成 backlog其中一项就是create_issue Add Amazon Q appendix to primitives matrix good first issue,docs $BODY_DIR/amazon-q-appendix.md对应的 amazon-q-appendix.md 定义了这份附录的验收标准共四条以Gemini CLI / Zed 附录的风格新增一个Amazon Q 附录覆盖调度scheduling、规则/上下文文件rules/context files、STATE.md、Maker/Checker 拆分四个方面在 Q 尚未把某个原语做成一等公民的地方给出诚实说明honest note提供一个可复制粘贴的第一周 Daily Triage 提示词只读、仅汇报。这份附录的成品正文已经合入 docs/primitives-matrix.md#L433-L492## Appendix: Amazon Q Developer CLI一节本文即以它为主体骨架结合仓库中的技能模板、状态样例与 CLI 工具源码做纵深展开。这也呼应了原语矩阵开头的那句总纲「工具无关的循环设计——能力capability才是关键而不是产品名」。Amazon Q 附录的使命就是把同一套循环形态映射到q chat这个具体宿主上。前置认知六大循环原语与「原语矩阵」的坐标系要理解 Amazon Q 附录在说什么先看它服务的框架。仓库在 docs/concepts.md 里定义了循环工程的六个原语外加记忆原语在循环中的职责Automations / Scheduling自动化/调度按节奏发现工作、执行分诊Worktrees工作树安全并行执行Skills技能沉淀可复用的项目知识Plugins Connectors插件与连接器触达真实工具MCP 等Sub-agents子代理Maker/Checker 拆分制造者与检核者分离Memory / State记忆/状态跨运行记录「已完成什么」docs/primitives-matrix.md 把这六个原语逐一映射到八种主流 Agent 环境Grok、Claude Code、Codex、OpenClaw、Opencode、Cursor、Windsurf、Hermes并在文末追加了多份「附录Appendix」逐一记录 Codeium/Windsurf、Aider、Roo Code、Continue.dev、Cline、Zed、Gemini CLI、GitHub Copilot、Amazon Q Developer CLI、Devin 等宿主各自的映射方式。Amazon Q 附录就是其中一份。Amazon Q Developer CLI 的定位见附录首段是终端型 Agent、AWS 原生、支持自定义 Agent 配置custom agent profiles与 MCP。它没有自己的STATE.md约定也没有内建调度器因此附录的写法与 Zed / Gemini CLI 附录一致把循环原语以「外部约定 配置文件 外部调度器」的方式手工叠加上去。原语映射总览Amazon Q Developer CLI 对照表附录的核心是一张「原语 → Q 的映射」表逐项说明每个原语在q chat中的落地方式原语Amazon Q Developer CLI 映射Scheduling调度无原生 cron 式调度器。使用外部调度器cron、systemd timer、GitHub Actions以非交互方式调用q chat或用q chat --resume在下次调度运行时继续已保存的「按目录隔离」的会话。Rules / Context files规则/上下文文件在.amazonq/agents/name.json项目级或~/.aws/amazonq/cli-agents/name.json个人级定义自定义 Agent并在其resources字段列出常驻上下文如file://STATE.md、file://.amazonq/rules/**/*.md。可用hooks.agentSpawn在会话启动时注入新鲜上下文如git status。State状态在仓库根目录维护STATE.md并在自定义 Agent 的resources字段中引用它使其每次会话都加载每次运行应先读取、再只更新相关小节。Maker/checker split制造/检核拆分无原生子代理/检核者原语。变通做法定义两个自定义 Agent如带写工具的daily-triage.json以及只开放fs_read/git的loop-verifier.json在独立的q chat --agent loop-verifier会话中对 diff 执行检核。Connectors连接器在.amazonq/mcp.json项目级或~/.aws/amazonq/mcp.json全局配置 MCP 服务器用allowedTools按 Agent 收敛工具信任范围。对不可信仓库的.amazonq/mcp.json要格外谨慎——打开前先审查因为自动加载的 MCP 配置对该类工具而言是真实存在的攻击向量。Honest gaps诚实缺口没有一等公民的调度器、没有内建的 Maker/Checker 分离、没有专门的状态文件约定——这些都只是叠加在q chat之上的手工约定与大多数没有专用循环调度器的终端 Agent 处境相同。下面逐项展开并给出可运行的配置与命令。调度Scheduling无原生 cron用外部调度器 --resume接力附录明确写到q chat没有原生 cron 式调度器。这意味着「每 5 分钟跑一次」或「每天早上跑一次」这类节奏必须交给仓库之外或仓库之内的外部调度器cron / systemd timer在宿主机器上注册定时任务非交互调用q chatGitHub Actions把循环绑定到 CI 事件或定时 workflowschedule触发q chat --resumeQ 会为每个目录保存会话--resume可在下一次调度运行时继续上一次的对话从而在多次运行之间保持上下文连贯。对比原语矩阵的 Scheduling Quick Referencedocs/primitives-matrix.md 中「Scheduling Quick Reference」一节可以看到其余宿主各有/loop 5m promptGrok/Claude Code、Automation, 5m cadenceCodex/Cursor、hermes cron createHermes之类的内建或半内建节奏而 Amazon Q 与 Zed、Gemini CLI 类似属于「编辑器/终端宿主 外部调度」一族。附录的诚实缺口因此排在表格第一位调度不是一等公民。规则与上下文文件Rules / Context files自定义 Agent 与resourcesQ 用「自定义 Agent 配置」承载循环的常驻知识。配置文件有两个层级项目级.amazonq/agents/name.json随仓库提交团队共享个人级~/.aws/amazonq/cli-agents/name.json仅自己使用。关键机制是resources字段它列出每次会话启动时自动加载的上下文文件支持file://URI 与 glob例如file://STATE.md、file://.amazonq/rules/**/*.md。这正好对应原语矩阵「Skills / 规则」的语义——把「每次运行都要记得的约定」写一次、每次会话自动读取从而偿还 docs/concepts.md 所说的Intent Debt意图债。附录给出了一个完整的项目级 Agent 配置.amazonq/agents/daily-triage.json{ name: daily-triage, description: Report-only daily triage agent, prompt: Run loop-triage. Update STATE.md with High Priority and Watch List only. Do not edit source code in week one., tools: [fs_read, fs_write], resources: [ file://STATE.md, file://.amazonq/rules/loop-triage.md ] }逐字段解读nameAgent 名之后用q chat --agent daily-triage调用description声明式描述帮助 Q 与协作者理解该 Agent 的用途这里是「只读每日分诊」prompt系统提示词等价于把SKILL.md的核心指令固化进 Agent——本例引用了loop-triage技能的精神只更新 High Priority / Watch List、第一周不改源码tools工具白名单[fs_read, fs_write]表示只允许读写文件不给终端/网络权限从工具层面保证「只读分诊」的边界resources每次会话自动加载STATE.md与规则文件让 Agent 一醒来就知道项目当前状态与循环约定。这里用到的规则文件loop-triage.md正是把仓库的 templates/SKILL.md.loop-triage 复制进.amazonq/rules/的结果见后文「最小迁移配方」。该技能定义了loop-triage的输入最近 CI/测试失败、未关闭 issue、main 分支近 24–48h 提交、聊天线索、当前状态文件与输出High-Priority Items/Watch Items/Noise / Ignore/State Updates四段式 Markdown 报告并要求「宁可在 Watch/Noise 里放也不要制造新工作」「分诊期间绝不提出架构级改造」——这份「只做信号、不做发明」的纪律正是第一周只读循环的行为准则。另外附录提到hooks.agentSpawn可在会话启动时注入新鲜上下文如git status——这弥补了resources只加载静态文件、无法自动感知「此刻仓库状态」的不足让每次调度运行都能基于最新的 git 现场做分诊。状态State以仓库根目录的STATE.md为记忆主干Q没有专门的状态文件约定附录给出的做法与 Zed / Gemini CLI / Aider 附录完全一致在仓库根目录提交STATE.md并在自定义 Agent 的resources里引用它确保每次会话都加载每次运行先读取、再只更新相关小节、并保留历史。仓库的状态样例 starters/minimal-loop/STATE.md.example 展示了推荐的STATE.md骨架# Loop State — My Project Last run: never ## High Priority (loop is acting or waiting on human) ## Watch List ## Recent Noise (ignored this run) ## Post-Run Critique (from last run) - High-noise: dependabot PRs surfaced again — add to ignore list - False positives: 1 CI flake (known flaky test) - Deprioritize: lint warnings moved to Watch List - Friction: triage missed nightly deploy failure (was infra, not code) - Adjustment: include infra check status in scan --- Run log: —值得注意Post-Run Critique小节——它让循环自我复盘记录噪声源、误报、优先级调整、摩擦点与改进项这正是 docs/concepts.md 强调的「用判断力设计循环而不是用循环逃避思考」。第一周运行后把「dependabot PR 反复出现」「某测试已知 flaky」这类观察写回状态文件循环就会越来越聪明。原语矩阵的「State Conventions」一节还给出了按循环类型选择状态文件名的约定docs/primitives-matrix.md文件用途STATE.md通用循环记忆每日分诊issue-triage-state.mdissue 队列健康度每日分诊的输入源pr-babysitter-state.mdPR 专属监视状态ci-sweeper-state.md活跃 CI 失败 尝试次数post-merge-state.md最近合入后的清理积压附录同时提醒Linear / GitHub Projects 也可以——关键是循环每次运行都要读写同一个存储状态主干必须是跨运行、跨工具、可审查的。Maker/Checker 拆分用两个自定义 Agent 模拟检核分离循环要无人值守地改代码就必须保证「制造者不能给自己的作业打分」docs/concepts.md 中的 Code Agent Orchestra / Adversarial Code Review 原则。而 Q没有内建的子代理/检核者原语附录给出的变通方案是定义两个自定义 Agentdaily-triage.jsonMaker/分诊端tools含fs_write负责分诊与更新状态loop-verifier.jsonChecker/检核端只开放fs_read与git负责审 diff不碰写工具。检核端的行为契约可以直接从仓库的 templates/SKILL.md.verifier 复制为loop-verifier的 prompt 核心。该技能给检核者立了五条硬性清单全部通过才算 APPROVEScope范围只改相关文件无 denylist 路径无无关编辑Intent意图改动确实针对声明的目标而不是另一个问题Tests测试检核者自己运行测试并附上输出片段——「不要相信制造者说测试通过了」No cheating不作弊无禁用测试、跳过断言、注释掉的检查Risk风险中高风险即使测试通过也要建议人工复查。输出采用统一判定格式Verdict: APPROVE | REJECT | ESCALATE_HUMAN附证据与 REJECT 原因。默认立场是「没有充分证据就 REJECT」环境问题无法跑测试则ESCALATE_HUMAN。L2可改代码阶段的检核流程附录给出了一段可复制的命令序列git diff diff.patch q chat --agent loop-verifier --no-interactive \ Act as loop-verifier. Review diff.patch against STATE.md goals. Report PASS/FAIL and do not edit files.先由 Maker 在受控范围内产出 diff 到diff.patch再由只读的loop-verifierAgent 在独立会话中对齐STATE.md目标给出 PASS/FAIL——两个 Agent、两个会话、两套工具权限从进程层面实现制造/检核分离。连接器Connectors / MCP.amazonq/mcp.json与信任边界Q 通过 MCP 触达外部工具配置文件同样分两级项目级.amazonq/mcp.json全局级~/.aws/amazonq/mcp.json。配合allowedTools可以按 Agent 收敛工具信任范围做到「发现/验证所需的最小权限」。如果第一周是只读分诊附录的建议是先禁用或最小化 MCP 工具把权限边界留在后面升级时再放开。附录在此处专门给出了安全警告对不可信仓库的.amazonq/mcp.json要小心——打开前先审查因为「自动加载的 MCP 配置对该类工具而言是真实存在的攻击向量」。这是把安全边界当成循环设计的一等公民来处理不要因为某个仓库自带 MCP 配置就盲目信任。作为对照本仓库自己也发布了一个 MCP 服务器配置示例在 examples/mcp/loop-engineering.mcp.json——把 patterns、skills、state、budget、safety 文档暴露为运行时可查询的 MCP 资源以减少提示词堆砌prompt stuffing。它的服务器本体在 tools/mcp-server/以npx -y cobusgreyling/loop-mcp-server启动并通过LOOP_PROJECT_ROOT指向项目根目录。如果要在 Q 里接入这类「文档即资源」的 MCP同样按.amazonq/mcp.json的格式登记即可。第一周 Daily Triage只读、可复制验收标准的最后一条是给一个开箱即用的第一周每日分诊命令。附录给出的完整命令如下--no-interactive保证可被外部调度器非交互调用q chat --agent daily-triage --no-interactive \ Run loop-triage. Read STATE.md first. Update only High Priority and Watch List sections. Do not edit source code in week one.这条命令的行为拆解--agent daily-triage加载.amazonq/agents/daily-triage.json从而自动带上resources里的STATE.md与规则文件提示词要求先读STATE.md状态主干优先只更新 High Priority 与 Watch List 两个小节状态写入的最小化原则避免污染其他区域第一周不改源码——循环只做信号收集与汇报任何代码改动都要经过人工决策。这与 templates/SKILL.md.loop-triage 的定位完全一致loop-triage是循环的「眼睛」负责产出「高优先 / 监视 / 噪声 / 状态更新」四段式报告绝不越界去发明架构或动手改码。整个第一周循环的产出是一个可审查的 Markdown 汇报人类根据它决定是否把某项升级为待办或实现——这正是 docs/concepts.md 所说的「设计循环用判断力用循环逃避思考才是加速器」的反面教材。最小迁移配方Minimal Transfer Recipe把上述所有文件落到一个全新项目上附录给出了一条可直接执行的迁移命令mkdir -p .amazonq/agents .amazonq/rules cp templates/SKILL.md.loop-triage .amazonq/rules/loop-triage.md cp starters/minimal-loop/STATE.md.example STATE.md之后按需创建.amazonq/agents/daily-triage.json抄上文配置与.amazonq/agents/loop-verifier.jsontools收敛到fs_read/git再把调度挂到 cron/systemd/GitHub Actions 上。附录在文末给出的「复制之后」收尾建议是在 Q 有一等公民的循环调度器之前把调度映射到 cron/systemd/GitHub Actions用.amazonq/rules/承载常驻仓库指引用两个独立自定义 Agent 实现 Maker/Checker 分离用.amazonq/mcp.json接入外部工具。迁移完成后可以用仓库的两个 CLI 工具做自检与脚手架对照# 审计循环就绪度L0-L3 建议 npx cobusgreyling/loop-audit . --suggest # 脚手架对照在支持的工具上生成 daily-triage npx cobusgreyling/loop-init . --pattern daily-triage --tool claude需要诚实说明的是从 tools/loop-init/src/cli.ts 的帮助文本看-t, --tool Tool target (default: claude)loop-init目前的--tool目标为grok|claude|codex|opencodeTOOL_SUFFIX映射表见 cli.ts#L36Amazon Q 尚未成为一等脚手架目标。因此对 Q 用户来说上文这条mkdir/cp手工迁移路径就是当前的正道——这与矩阵中 OpenClaw、Hermes 等宿主的过渡方案先手工桥接、再等loop-init支持是同一条路径。诚实缺口Honest Gaps与升级路径附录最后把 Q 的边界讲得很直白三句话概括没有一等公民的调度器——节奏必须外包给 cron/systemd/GitHub Actions没有内建的 Maker/Checker 分离——靠两个自定义 Agent 两个独立会话手工模拟没有专门的状态文件约定——STATE.md是仓库层面的手工约定。这三点不是缺陷的遮羞布而是设计输入正因为调度器、检核者、状态文件都不是内建能力循环设计者才必须把它们显式地写进.amazonq/配置与外部调度里从而获得与其余宿主完全可迁移、可审计、可交接的一致性。从 L1只读分诊升级到 L2受控改码的路径也随之清晰启用带写工具的 Maker Agent、在独立工作树产出 diff、用只读loop-verifier会话做 PASS/FAIL 检核、最终由人类做合入门禁——参考 docs/safety.md 中的路径拒绝清单denylist思想secrets、billing、auth 等敏感路径在 Q 里同样应要求显式人工批准。结语同一套循环换一个宿主Amazon Q Developer CLI 不是为循环工程而生的调度中枢但通过「原语矩阵」这套工具无关的坐标系它和 Zed、Gemini CLI、Aider 等宿主一样可以被组织成完整的循环系统外部调度器负责节奏resources承载规则与状态双 Agent 模拟 Maker/Checker 分离allowedTools收敛权限边界而STATE.md成为跨运行、跨工具的记忆主干。原语矩阵附录docs/primitives-matrix.md的「Choosing a Tool」一节给了四条迁移心法正好是本文的收束先写好工具无关的SKILL.mdtemplates/ 里有一整套可复用模板定义好状态 schemaMarkdown 或 JSON文档化检核拆分谁检查谁最后才把调度映射到当前宿主TUI、编辑器或 Action。对 Q 用户而言第 4 步就是本文这份附录的全部内容——能力在循环里产品名只是它的载体。【免费下载链接】loop-engineeringPractical patterns, starters CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.项目地址: https://gitcode.com/gh_mirrors/lo/loop-engineering创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考