撰写智能体简报Agent Brief智能体简报是在问题或 PR 转移到ready-for-agent时发布在 GitHub 问题或 PR 上的结构化评论。它是 AFK异步智能体将据此工作的权威规范。原始正文和讨论只是上下文——智能体简报才是契约。简报陈述智能体应该做什么这延伸到两个表面对于问题即从零开始构建该更改对于 PR即对现有 diff还剩下什么要做——完成它、弥合差距、处理审查意见。两种情况下原则相同下面的 PR 示例展示了差异。原则持久性优先于精确性问题可能在ready-for-agent状态下停留数天或数周。与此同时代码库会发生变化。撰写简报时应使其在文件被重命名、移动或重构后仍然有用。要描述接口、类型和行为契约要指明智能体应查找或修改的特定类型、函数签名或配置形状不要引用文件路径——它们会过时不要引用行号不要假设当前的实现结构会保持不变描述行为而非过程描述系统应该做什么而不是如何实现。智能体将重新探索代码库并做出自己的实现决策。好“TheSkillConfigtype should accept an optionalschedulefield of typeCronExpression”SkillConfig类型应接受一个可选的schedule字段类型为CronExpression坏“Open src/types/skill.ts and add a schedule field on line 42”打开 src/types/skill.ts 并在第 42 行添加一个 schedule 字段好“When a user runs/triagewith no arguments, they should see a summary of issues needing attention”当用户不带参数运行/triage时他们应看到需要关注的问题摘要坏“Add a switch statement in the main handler function”在主处理函数中添加一个 switch 语句完整的验收标准智能体需要知道何时算完成。每份智能体简报都必须有具体、可测试的验收标准。每条标准都应可独立验证。好“Runninggh issue list --label needs-triagereturns issues that have been through initial classification”运行gh issue list --label needs-triage返回已经过初步分类的问题坏“Triage should work correctly”分诊应正常工作明确的范围边界陈述哪些内容超出范围。这可以防止智能体过度设计或对相邻功能做出假设。模板## Agent Brief **Category:** bug / enhancement **Summary:** one-line description of what needs to happen **Current behavior:** Describe what happens now. For bugs, this is the broken behavior. For enhancements, this is the status quo the feature builds on. **Desired behavior:** Describe what should happen after the agents work is complete. Be specific about edge cases and error conditions. **Key interfaces:** - TypeName — what needs to change and why - functionName() return type — what it currently returns vs what it should return - Config shape — any new configuration options needed **Acceptance criteria:** - [ ] Specific, testable criterion 1 - [ ] Specific, testable criterion 2 - [ ] Specific, testable criterion 3 **Out of scope:** - Thing that should NOT be changed or addressed in this issue - Adjacent feature that might seem related but is separate示例好的智能体简报缺陷## Agent Brief **Category:** bug **Summary:** Skill description truncation drops mid-word, producing broken output **Current behavior:** When a skill description exceeds 1024 characters, it is truncated at exactly 1024 characters regardless of word boundaries. This produces descriptions that end mid-word (e.g. Use when the user wants to confi). **Desired behavior:** Truncation should break at the last word boundary before 1024 characters and append ... to indicate truncation. **Key interfaces:** - The SkillMetadata types description field — no type change needed, but the validation/processing logic that populates it needs to respect word boundaries - Any function that reads SKILL.md frontmatter and extracts the description **Acceptance criteria:** - [ ] Descriptions under 1024 chars are unchanged - [ ] Descriptions over 1024 chars are truncated at the last word boundary before 1024 chars - [ ] Truncated descriptions end with ... - [ ] The total length including ... does not exceed 1024 chars **Out of scope:** - Changing the 1024 char limit itself - Multi-line description support好的智能体简报增强## Agent Brief **Category:** enhancement **Summary:** Add .out-of-scope/ directory support for tracking rejected feature requests **Current behavior:** When a feature request is rejected, the issue is closed with a wontfix label and a comment. There is no persistent record of the decision or reasoning. Future similar requests require the maintainer to recall or search for the prior discussion. **Desired behavior:** Rejected feature requests should be documented in .out-of-scope/concept.md files that capture the decision, reasoning, and links to all issues that requested the feature. When triaging new issues, these files should be checked for matches. **Key interfaces:** - Markdown file format in .out-of-scope/ — each file should have a # Concept Name heading, a **Decision:** line, a **Reason:** line, and a **Prior requests:** list with issue links - The triage workflow should read all .out-of-scope/*.md files early and match incoming issues against them by concept similarity **Acceptance criteria:** - [ ] Closing a feature as wontfix creates/updates a file in .out-of-scope/ - [ ] The file includes the decision, reasoning, and link to the closed issue - [ ] If a matching .out-of-scope/ file already exists, the new issue is appended to its Prior requests list rather than creating a duplicate - [ ] During triage, existing .out-of-scope/ files are checked and surfaced when a new issue matches a prior rejection **Out of scope:** - Automated matching (human confirms the match) - Reopening previously rejected features - Bug reports (only enhancement rejections go to .out-of-scope/)好的智能体简报PR对于 PR“Current behavior”当前行为描述 diff 的状态简报要求智能体完成或修复它而不是从零构建。## Agent Brief **Category:** enhancement **Summary:** Finish the contributors --json output flag for triage list **Current behavior:** The PR adds a --json flag that serializes the issue list to JSON. The happy path works and the diff matches the projects command structure. Two gaps remain: errors are still printed as human text (not JSON), and the new flag has no test coverage. **Desired behavior:** With --json, all output — including errors — is well-formed JSON on stdout, and the commands exit codes are unchanged. The existing human-readable output is untouched when the flag is absent. **Key interfaces:** - The commands error path should emit { error: string } under --json instead of the plain-text error - Reuse the existing serializer the PR already added; dont introduce a second **Acceptance criteria:** - [ ] triage list --json emits valid JSON for both success and error cases - [ ] Exit codes match the non-JSON command - [ ] A test covers the --json success output and one error case - [ ] Default (non-JSON) output is byte-for-byte unchanged **Out of scope:** - Adding --json to any other command - Changing the JSON shape of the success payload the PR already defined坏的智能体简报## Agent Brief **Summary:** Fix the triage bug **What to do:** The triage thing is broken. Look at the main file and fix it. The function around line 150 has the issue. **Files to change:** - src/triage/handler.ts (line 150) - src/types.ts (line 42)这很糟糕因为没有类别描述模糊“the triage thing is broken”引用了会过时的文件路径和行号没有验收标准没有范围边界没有描述当前行为与期望行为的对比