企业官网建设流程全解析

撰写智能体简报（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 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

示例

好的智能体简报（缺陷）

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

好的智能体简报（增强）

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

坏的智能体简报

## 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”）
• 引用了会过时的文件路径和行号
• 没有验收标准
• 没有范围边界
• 没有描述当前行为与期望行为的对比