Agent Brief

Agent Brief

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills

Category:bug / enhancementSummary: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 agent's 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

各字段要点： | 字段 | 作用 | 写作要点 | | --- | --- | --- | | `Category` | 区分 bug / enhancement | 对应 triage 技能中的两个**类别角色**，见 [SKILL.md](https://link.gitcode.com/i/90a425aece6d8764367b9233bca50405) | | `Summary` | 一句话概括 | 让维护者和智能体在列表中一眼定位 | | `Current behavior` | 描述现状 | bug 描述故障行为；enhancement 描述该功能依托的现状 | | `Desired behavior` | 描述目标 | 务必具体到**边界情况与错误条件** | | `Key interfaces` | 点名关键类型/签名/配置形状 | 只描述契约，不描述文件位置 | | `Acceptance criteria` | 可验证的完成标准 | 每条可独立验证，写成可勾选列表 | | `Out of scope` | 边界声明 | 防止过度加工与相邻功能误改 | ## 四、范例一：Bug 类 Agent Brief（完整示范） 当智能体以"修复 bug"为目标时，`Current behavior` 记录的是当前故障行为。以下为完整范例： ```markdown ## 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` type's `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

注意它的示范价值：Key interfaces直接点名SkillMetadata类型的description字段及其校验/处理逻辑，但不给出文件路径；Acceptance criteria用四个可勾选项覆盖了正常长度、超长截断、省略号后缀、总长度上限四种可独立测试的情况；Out of scope明确排除了"修改 1024 上限"和"多行描述支持"两个相邻议题。

五、范例二：Enhancement 类 Agent Brief（完整示范）

当智能体以"新增/改进功能"为目标时，Current behavior描述的是该功能所依托的现状。同时注意，这个范例的产出物（.out-of-scope/目录）与本仓库 OUT-OF-SCOPE.md 描述的知识库机制完全一致，可直接交叉印证：

## 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/`)

值得注意：Key interfaces用"Markdown 文件格式 + triage 工作流行为"来定义契约，而不是指定某个源文件；Acceptance criteria里明确区分了"首次创建/追加去重/新 issue 命中提醒"三种路径，且Out of scope把"自动化匹配"排除——这与 OUT-OF-SCOPE.md 中"匹配由人确认（human confirms the match）"的规则严丝合缝。

六、范例三：PR 类 Agent Brief（完整示范）

PR 与 issue 的差异在于："Current behavior"描述的是当前 diff 的状态，Brief 要求智能体去完成或修复这个 diff，而不是从零构建。这在 triage 技能中也有对应表述——ready-for-agent对 PR 而言意味着"已附加 Brief，智能体应针对 diff 采取下一步行动"。

## Agent Brief **Category:** enhancement **Summary:** Finish the contributor's `--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 project's 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 command's exit codes are unchanged. The existing human-readable output is untouched when the flag is absent. **Key interfaces:** - The command's error path should emit `{ "error": string }` under `--json` instead of the plain-text error - Reuse the existing serializer the PR already added; don't 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

这个范例特别示范了"增量委托"的精髓：Current behavior明确承认 happy path 已可用、diff 结构合规，只点出两个剩余缺口（错误路径未 JSON 化、无测试覆盖）；Desired behavior用"exit codes 不变""非 JSON 输出 byte-for-byte 不变"给出回归约束；Key interfaces甚至要求复用 PR 中已有的 serializer 而非另写一套——这些都是防止智能体重写贡献者代码的护栏。

七、反面教材：Bad Agent Brief 及其六宗罪

原文档给出了一个反例，并在文末列出了诊断：

## 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)

【免费下载链接】skillsSkills for Real Engineers. Straight from my .agents directory.项目地址: https://gitcode.com/GitHub_Trending/skills13/skills