agile-refinement

精炼

使用此技能验证规划制品并审查代码质量。它有两种模式：规划检查和代码审查。

通过斜杠命令收到的初始上下文：$ARGUMENTS

如果 $ARGUMENTS 不为空（例如，文件路径、分支、“planning”或“code”），请据此确定起始模式。 如果为空，请询问用户想要验证什么：规划制品还是代码更改。

语言

使用用户的语言撰写所有报告。遵循正确的语法，并使用所需的变音符号或特定文字系统字符。如果无法确定用户使用的语言，请在生成输出前询问。

项目根目录

此技能会在相对于项目根目录（即执行工作的仓库）的路径下写入制品，而不是相对于 Agent 当前的工作目录。

• 如果从项目内部调用，请使用此技能中所示的相对路径。
• 如果从其他目录调用（例如，来自相邻仓库，或项目位于其他位置），请在每个制品路径前添加 <project-root>/。
• 如果项目根目录不明确，请在写入前通过 harness 的提问工具与用户确认。

提问

遵循项目范围内 CLAUDE.md / AGENTS.md 中的约定（“Skill Prompting Conventions”）。在以下决策点使用 harness 的结构化提问工具：AskUserQuestion（Claude Code）、ask_user_question（Codex）或 question（OpenCode）。

决策点	采用结构化提问的原因	建议选项
目标	决定工作流分支	规划制品 · 代码 · 两者
深度	影响审查工作量	仅检查 · 完整审查 · 安全重点

自由文本提示（不使用结构化工具）：

• 要审查的文件路径
• 特定关注点

无暂停模式：如果用户明确禁用了技能执行过程中的澄清步骤，请将每个结构化提示转换为“未解决问题”或同等部分中的条目，并继续执行，不要暂停等待答复。

目标

• 验证规划制品的一致性、完整性和正确性
• 审查代码更改的安全性、连贯性、范围和质量
• 在问题影响执行前发现它们
• 提供可执行的具体反馈，而非泛泛而谈

适用场景

• 开始实现前——检查规划制品
• 提交代码前——审查差异
• 创建拉取请求时——作为质量关卡
• 审查 AI 生成的代码时——进行与人工审查同等的审查
• 定期检查——检查内容是否过时、交叉引用是否失效，或制品是否孤立
• 合并或完成史诗时——验证各部分是否相互衔接

不适用场景

• 创建规划制品——使用 /agile-intake、/agile-epic、/agile-story、/agile-roadmap
• 将工作拆分为故事——使用 /agile-epic（现在由它负责拆分）
• 跟踪交付进度——使用 /agile-status
• 规划迭代——使用 /agile-sprint

模式 1：规划检查

根据以下检查项验证规划制品：

交叉引用

• 来源字段指向现有文件
• 所引用的史诗、故事和任务均存在
• 交叉引用中的文件路径正确，且文件均已存在

依赖关系

• 故事/任务之间声明的依赖关系均存在
• 不存在循环依赖
• 依赖顺序与路线图/史诗序列一致

完整性

• 包含必需章节（Context、Files、Detail、Tasks、Verification）
• 必填字段均不为空
• 验收标准明确且可验证
• 任务具体且可执行（而非含糊不清）

产品可追溯性

• 当存在原型时，以界面为主的史诗/故事应引用原型路由/界面
• 当存在业务规则时，领域行为应引用 business/*.md 中的规则 ID/文件
• 原型中不应包含作为产品可见文案的内部实现说明或业务规则说明
• 原型审查中发现的业务规则已记录在原型之外
• 规划材料中不包含原始机密、提供商密钥、令牌或凭据

一致性

• 相关材料（史诗中的故事）之间的规模评估保持一致
• 状态字段为最新
• 各文件的命名规范一致

格式

• 文件命名遵循规范（00-overview.md、NN-story-name.md）
• 文件夹结构遵循规范（planning/<initiative>/epics/NN-<epic>/）
• 模板已正确填写（没有遗留的占位文本）

范围冲突

• 同一史诗中的故事之间没有范围重叠
• 任务中没有提及范围外的事项

过时内容

• 没有所有任务均已完成但状态仍为“进行中”的材料
• 没有引用已删除或已移动的文件
• 没有超过 30 天、任务未完成且没有近期每日记录的计划

流程

1. 确定范围：单个文件、史诗文件夹或整个 planning/ 目录树。
2. 阅读范围内的所有材料。
3. 执行上述每个检查类别。
4. 按类别分组生成内联报告，并列出具体问题及其位置。

模式 2：代码审查

根据 ~/.agents/rules/code-review.md 中的检查清单审查已更改的代码：

安全性

• 已验证并清理输入
• 不存在 SQL 注入、XSS、命令注入或 SSRF
• 没有硬编码的机密
• 在适用情况下，身份验证和授权正确
• 日志或响应中不会暴露敏感数据

项目一致性

• 遵循仓库中的模式和规范
• 使用现有组件、实用工具和辅助函数
• 没有重复造轮子
• 命名与代码库保持一致
• 导入符合项目规范

过度设计

• 没有过早抽象
• 没有针对不可能情形的错误处理
• 没有针对假设性需求进行泛化

范围

• 代码只完成了请求的内容
• 没有重构无关代码
• 没有添加未请求的功能

质量

• 测试覆盖验收场景
• 无需解释性注释即可读懂代码
• 函数简短且职责单一
• 没有重复逻辑
• 在系统边界处处理错误

完整性

• Lint 检查通过
• 类型检查通过
• 测试通过
• 已完整阅读差异

流程

1. 确定范围：分支、文件或工作树中的更改。
2. 完整阅读差异后再输出任何内容。
3. 执行每个检查类别。
4. 按类别分组生成内联报告。
5. 标出足以支持立即拒绝的危险信号。

输出

此技能不会生成已保存的材料。它会生成内联报告，包含：

• 按类别分组的问题
• 严重程度：危险信号（拒绝）、警告（继续前修复）、提示（可考虑）
• 适用时，列出具体文件和行号
• 针对每个问题提供可执行的建议

规则

• 输出任何内容前，先阅读范围内的所有内容。
• 具体明确。“代码很差”无法指导行动。“将 src/middleware/rate-limit.ts 第 42 行的 RateLimitError 替换为 HttpError”才有帮助。
• AI 代码审查不能取代人工代码审查，而是额外的一道关卡。
• 可随时运行规划 lint——这是健康检查，不是仪式。
• 绝不提供模糊、笼统的反馈。每个问题都必须可验证。

与工作流的关系

flowchart LR
    A["/agile-epic"] --> B["/agile-refinement<br>(planning lint)"]
    C["/agile-story"] --> D[execution]
    D --> E["/agile-refinement<br>(code review)"]
    E --> F["/agile-status"]

此技能可在工作流中的任何阶段验证材料和代码。要创建规划材料，请使用 /agile-epic 或 /agile-story。要跟踪交付进度，请使用 /agile-status。