面向 Antigravity 的委托任务简报（Brief）写作实战：基于 agentic-awesome-skills 的 agy-delegate 完整指南

面向 Antigravity 的委托任务简报Brief写作实战基于 agentic-awesome-skills 的 agy-delegate 完整指南【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills导读在 agentic-awesome-skills 仓库的agy-delegate技能中brief任务简报是编排者orchestrator交给 Google Antigravity CLIagy执行的唯一输入Antigravity 在一条独立会话中运行它没有你对话的记忆、看不到你之前的笔记、也不共享任何上下文——它只能看到你发过去的文本以及在工作区里能自己检查到的内容。本指南以 writing-the-brief.md 为主体完整拆解一份高质量 brief 的结构、XML 块设计、真实 gate 命令的发现方法、模型选择与前提冻结纪律并给出可直接复制改写的完整示例。读完你将掌握如何用一份只读一次就能执行到底的 brief把有界编码任务安全委托出去并保证收到一份可评审、可落地的结构化报告。一、先理解 Brief 的本质约束不写进 brief 就等于不存在这是整个委托模型的第一性原理任何约束只要不在 brief 里、也无法从仓库中发现对 Antigravity 来说就是不存在的。编排者与 Antigravity 之间没有任何私聊频道。你无法在它运行中补一句顺便别动那个文件也无法纠正它基于错误前提做出的判断。因此 brief 必须是一次性的、自包含的任务说明书它要覆盖目标是什么、代码在哪里当前状态是什么、要改什么明确不要碰什么leave untouched 清单是防止 Antigravity 漫游到无关重构的关键项目真实的测试、lint、构建/类型检查命令一份要求它按固定格式输出的报告契约。关于离开清单的重要性从源码结构看action_safety块的存在就是专门用来约束实现者不要做无关重构、不要擅自提交的。把这条纪律前置到 brief 里是保证 diff 可评审的前提。在 SKILL.md 中这一步被定义为整个委托循环的第 1 步Write the brief后续的派发Dispatch、等待Wait、评审Review、落地Land都依赖这份 brief 的质量——可以说brief 写得有多好这次委托的上限就有多高。二、模型选择默认模型优先delta brief 只发给恢复的会话agy有一个配置好的默认模型因此一次全新的派发不需要传--model。只有人类明确为本任务指定了偏好的 Antigravity 模型标签时才显式传递--model。agy models # 列出可用的模型标签两条实用规则全新派发直接用 Antigravity 的配置默认值不要替它猜测恢复运行resume恢复的会话会保留对话上下文此时只发送增量 briefdelta brief即只描述相对于上一轮需要修正或追加的部分不要重复整份任务描述。这在返工循环见 review-and-land.md 中的--resume-last用法中是控制 token 与保持上下文一致的关键。三、四块骨架能覆盖大多数实现任务的结构Antigravity 对紧凑、分块、带 XML 标签的提示词响应最佳而不是冗长的散文。标准骨架由四个块组成陈述任务、定义完成、约定默认行为、约束少数真正重要的边界。task One or two sentences: the concrete job and where it lives. Then the specifics - current state, what to change, and explicitly what to leave untouched. The leave untouched list is what keeps Antigravity from wandering into unrelated refactors. /task verification_loop Run these before finishing and fix anything they surface, dont just report it: the projects real test command the projects real lint/format command the projects real build/typecheck command Confirm the working tree shows only the intended changes afterward. /verification_loop action_safety Keep changes scoped to the task. No unrelated refactors, renames, or cleanup unless required for correctness. Do NOT run git add or git commit - the orchestrator commits after reviewing. Leave the work uncommitted in the working tree. /action_safety structured_output_contract End with a report in this exact shape: 1. What changed and why 2. Files touched 3. Gate outcomes (paste the test/lint counts) 4. Anything you deviated on, left open, or want a decision on /structured_output_contract逐块解读其设计意图task用一到两句话说清具体工作与位置再补充当前状态、要改什么、明确不碰什么。最后一条最重要——没有它实现者会顺手做无关重构verification_loop要求它在收尾前运行并把问题修绿而不是报告一下问题就完事随后确认工作区只出现预期的改动action_safety把改动范围钉死在任务内并明确不要git add/git commit——提交由编排者在评审后完成工作区保持未提交状态structured_output_contract强制它按固定四段格式收尾报告这是后续可评审性的保障。四、按任务画像扩展额外块四块骨架覆盖大多数实现类任务但不同任务画像需要补充专属块调试 / 开放式修复completeness_contract要求彻底解决不要停在第一个看似合理的修复上missing_context_gating缺失的仓库事实不要猜测要么找到要么明确说明未知项。研究 / 建议类任务research_mode要求把观察到的事实observed facts、推断inferences、**开放问题open questions**分开陈述避免结论混杂。原则是任务需要时才加块不要为所有任务堆砌全部块。五、报告必须显式索取structured_output_contract 的价值relay 会把agy --print的 stdout 捕获为result.json中的finalMessage字段。如果 Antigravity 结束时没有收尾总结这个结果对评审毫无用处。node skill-dir/scripts/relay.mjs --brief brief.txt --cd /path/to/repo正是structured_output_contract块保证了你能读到一份报告改了什么、为什么动了哪些文件gate 结果贴出测试/lint 计数以及它偏离、遗留或需要你决策的事项。从 dispatch-and-poll.md 的result.json契约可以看到finalMessage是评审的起点而touchedFiles是基于git status --porcelain生成的评审起点清单——两者配合才能把自报与实况对照着看。六、发现真实的 gate 命令brief 里必须写项目实际的命令verification_loop只有在写入了项目真实命令时才有效。写 brief 之前先读仓库的AGENTS.md/CLAUDE.md/Makefile/package.json把真实命令抄进去make test npm run lint cargo test pytest -q一份只写run the tests却不指名命令的 brief得到的是一个靠猜或干脆跳过的实现者。这也解释了为什么本仓库的根目录维护了 AGENTS.md 这样的编排约定文件——它正是编排者在写 brief 时提取真实 gate 与仓库惯例的第一手来源。七、尊重仓库惯例把承重规则直接写进 brief如果项目在AGENTS.md、CLAUDE.md或类似文件中有house rules家规把其中**承重load-bearing**的几条在 brief 里复述。Antigravity 虽然能自行检查工作区但当重要规则直接摆在它面前时合规更可靠。这不是冗余——是对brief 是唯一指令通道这一事实的服从。八、一个任务一份 brief保持有界每个 brief 只承载单一、有界的工作。像Review this, fix what you find, update the docs, and suggest a roadmap这种大杂烩会产生一团混乱的运行结果——把它拆成多次派发。One brief → One Antigravity run → One commit这条纪律让评审和回滚都保持干净。在 multi-task-queues.md 中这一纪律被扩展为队列模式顺序执行、每任务一个 commit前一个任务落地评审 gate commit后才派发下一个因为后面的任务往往假设前面任务的产物已存在且干净的工作区保证每个任务的touchedFiles只显示它自己的改动。九、前提在派发时冻结派发前审计事实块实现者从 brief 的事实出发开始工作运行中途没有转向通道。因此发送前必须审计事实块所有权、目标分支、约束以及任何判断所依赖的前提。如果运行期间发现某个前提错了停止运行重新派发一份修正后的 brief而不是事后打折看待它的输出对于可写运行检查工作树把部分应用或受错误前提污染的编辑先理清保留或回退再重新派发。换句话说把 brief 当成一份发出即冻结的合同把纠错动作放到重新发合同上而不是事后给产出打折。十、完整示例一份可直接改写的 production 级 brief以下示例来自 writing-the-brief.md完整覆盖了 task 定位、真实 gate、行动安全与报告契约task In the payments service at services/billing/, the refund path double-charges when a refund is retried after a network timeout. Make refund submission idempotent: check for an existing refund by idempotency key before creating a new one. Touch only services/billing/refund.py and its tests. Leave the charge path, API routes, and data models untouched. /task verification_loop Run and make green before finishing: pytest tests/billing/ -q ruff check services/billing/ Confirm git status shows only refund.py and its test file changed. /verification_loop action_safety Scope strictly to the refund idempotency fix. No unrelated refactors. Do NOT git add or commit; leave changes in the working tree for review. /action_safety structured_output_contract Report: (1) the root cause and your fix, (2) files touched, (3) pytest ruff outcomes with counts, (4) anything you left open or want decided. /structured_output_contract注意几个可复用的细节task 里给出了精确路径与边界services/billing/refund.py及其测试明确排除 charge 路径、API 路由、数据模型verification_loop 里是真实命令pytest tests/billing/ -q与ruff check services/billing/并附带git status 应只显示两个文件的期望action_safety 明确了不提交、不做无关重构structured_output_contract 规定了四段式报告。十一、把 brief 放进完整委托循环写好 brief 只是第 1 步。完整循环在 SKILL.md 中定义第 1、4、5 步是你的判断第 2、3 步是机械操作写 brief本文主题派发node skill-dir/scripts/relay.mjs --brief brief.txt --cd /path/to/reporelay 包装agy --print并写出结构化result.json等待完成以result.json写入且进程退出为完成标志不要相信进度条评审不要信任自报——亲自重跑 gate、对照 brief 读 diff、对生成代码做系统性扫描硬编码成功、吞错、未验证的 import/API、死代码等详见 review-and-land.md落地实现者只改工作树提交由编排者完成需要修改时用--resume-last发送 delta brief 再评审一轮。派发、result.json契约、故障恢复agy_unavailable、timeout、aborted、headless 写权限被拒等的完整细节见 dispatch-and-poll.md。小结一份好 brief 的检查清单单一、有界任务一个 brief 对应一次运行、一个 commitXML 四块骨架齐全task / verification_loop / action_safety / structured_output_contracttask 里有明确的不要碰清单verification_loop 里是项目真实的 test / lint / build 命令先读AGENTS.md/Makefile/package.jsonaction_safety 里写明不提交、留工作区未提交状态structured_output_contract 保证了可读的四段式报告调试类任务补充completeness_contract与missing_context_gating研究类任务补充research_mode派发前完成前提审计运行中前提错误则停止并重发修正 brief。记住那句贯穿始终的原则如果约束不在 brief 里、也无法从仓库中发现对 Antigravity 来说它就不存在。把这条纪律内化你的每次委托都会从碰运气变成可预期。【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址: https://gitcode.com/gh_mirrors/an/agentic-awesome-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考