address-ticket

读取当前分支对应的 JIRA 工单，并使用多 Agent 团队和 TDD 推动工单完成：由 PO 编写需求，开发者批准，然后提出并评审测试计划。确认后，先编写测试（红），再实现生产代码使测试通过（绿）。

用法：

• /address-ticket - 获取工单，并与团队协作推动其完整实现
• /address-ticket --no-jira <instructions> - 跳过 JIRA 获取步骤，将提供的说明作为工单上下文
• /address-ticket --headless - 全自动执行：由评审 Agent 验证需求和测试计划，无需询问开发者
• /address-ticket --no-jira --headless <instructions> - 两个标志可以组合使用

说明：

阶段 0 — 解析标志

0. 扫描 $1、$2、$3 中的标志：

   两个可选标志可按任意顺序出现：--no-jira 和 --headless。其余非标志参数均为用户说明。

   • --headless 模式： 如果 $1、$2、$3 中任意一个是 --headless，则设置 headless = true。在 headless 模式下，绝不询问开发者是否批准。改由评审子 Agent 自主验证需求和测试计划（见步骤 10 和 14）。
   • --no-jira 模式： 如果 $1、$2、$3 中任意一个是 --no-jira：
     • 第一个非标志参数是用户说明，即工单上下文（需要构建、修复或更改的内容）
     • 如果未提供用户说明，使用 AskUserQuestion 询问开发者描述任务：

       你使用了 --no-jira，但未提供说明。请描述需要实现的内容。

     • 完全跳过以下步骤： 步骤 1（acli 验证）、2（提取 JIRA ID）、3（获取 JIRA 工单）、4（获取 Figma 信息）、8（维护 lore 文件），以及阶段 4 中所有与 JIRA 更新相关的步骤（步骤 18–19）
     • 继续执行： 步骤 5（常规提交前缀——根据用户说明和分支名称推断）、步骤 6（代码库分析——将用户说明作为工单上下文）、步骤 7（拆分评估——使用用户说明）
     • 后续所有阶段中，凡技能通常引用“JIRA 工单内容”或“工单字段”的地方，都使用用户说明
     • 在最终报告（步骤 19）中，将“JIRA Ticket”部分替换为：

       ### 来源
       - 模式：--no-jira（用户说明）
       

   • 如果两个标志都未出现，则正常进入步骤 1

阶段 1 — 收集上下文

1. 验证 Atlassian CLI 是否可用且已通过身份验证：

   • 运行 acli auth status 检查 CLI 是否已安装且已通过身份验证
   • 如果找不到该命令，显示以下错误并停止：

     Atlassian CLI (acli) is not installed.
     This skill requires the Atlassian CLI.
     Install it with: brew tap atlassian/acli && brew install acli
     

   • 如果命令因身份验证错误而失败，显示以下错误并停止：

     Atlassian CLI is not authenticated.
     This skill requires an authenticated Atlassian CLI.
     Please run `acli auth login` to authenticate before using /address-ticket.
     

2. 从当前分支名称中提取 JIRA ID：

   • 运行 git branch --show-current 获取当前分支名称
   • 通过匹配模式 [A-Z][A-Z0-9]+-[0-9]+ 提取 JIRA ID（例如：PROJ-123、AB-1、MYAPP-4567）
   • JIRA ID 可以出现在分支名称的任意位置（例如：fix/PROJ-123、feat/PROJ-123、PROJ-123-some-description、feature/PROJ-123-add-login）
   • 如果分支名称中未找到 JIRA ID，显示以下错误并停止：

     No JIRA ID found in branch name: "<current-branch>"
     Expected a branch name containing a JIRA ID (e.g., PROJ-123).
     Examples: fix/PROJ-123, feat/MYAPP-456, PROJ-123-add-login
     

3. 获取 JIRA 工单：

   • 使用 Atlassian CLI 按 JIRA ID 检索问题：

     acli jira workitem view <JIRA-ID> --fields '*all' --json
     

   • 这会获取工单上的所有可用字段。除标准字段（摘要、描述、问题类型、优先级、评论）外，还要使用所有能提供有用背景信息的字段——例如，Bug 通常包含“预期行为”和“实际行为”字段，故事可能包含“验收标准”字段等。自定义字段因项目而异，因此请阅读工单提供的所有内容。

   • 附件：JSON 响应中包含一个 attachment 数组，其中列出了每个附件的元数据（id、filename、content、mimeType、size）。acli CLI 没有内置的附件下载命令，因此请使用 Jira REST API，并通过 acli 身份验证令牌下载附件。

     a) 创建本地附件目录：

     mkdir -p /tmp/<JIRA-ID>-attachments
     

     b) 通过 Jira REST API 下载每个附件。 每个附件对象都包含一个 content 字段——这是 REST API 下载 URL（格式：https://<site>.atlassian.net/rest/api/3/attachment/content/<id>）。使用 acli auth token 进行身份验证：

     curl -s -L -H "Authorization: Bearer $(acli auth token)" \
       -o "/tmp/<JIRA-ID>-attachments/<filename>" \
       "<content-url>"
     

     如果响应中缺少 content URL，请根据站点 URL（从 self 字段中提取）和附件 id 手动构造：

     curl -s -L -H "Authorization: Bearer $(acli auth token)" \
       -o "/tmp/<JIRA-ID>-attachments/<filename>" \
       "https://<site>.atlassian.net/rest/api/3/attachment/content/<attachment-id>"
     

     对数组中的每个附件重复此操作。下载所有附件，包括图片（屏幕截图、模型图、示意图）、文档（PDF、CSV）、数据文件（JSON、XML）、日志、配置文件等。

     c) 分析已下载的文件：

     • 图片（PNG、JPG、GIF、SVG、WebP）：阅读图片以了解视觉背景——UI 预期效果、Bug 屏幕截图、模型图、示意图、工作流图示
     • 基于文本的文件（CSV、JSON、XML、日志文件、配置文件、.txt）：阅读文件内容，以提取数据、错误模式、配置详情或复现步骤
     • PDF：阅读其中的需求、规格说明或设计文档
     • 其他格式：记录文件名和 MIME 类型；如果无法读取，则跳过

     d) 跟踪所有已下载文件的路径——这些路径将传递给 PO、测试规划人员、测试编写人员和开发者 Agent，确保每个 Agent 都能访问工单的原始附件。

   • 如果单个附件下载失败，或文件太大而无法处理，请继续处理其余附件，同时通知开发者：

     无法下载/分析附件：“<filename>”（<原因：下载失败 / 文件过大 / 格式不受支持 / 等>）
     继续使用现有信息。
     

   • 如果获取 JIRA 工单失败（问题不存在、权限被拒绝等），请提供备用方案：使用 AskUserQuestion 询问开发者是否希望手动粘贴工单内容。如果开发者拒绝，则停止。如果开发者提供了内容，则继续处理。

4. 获取 Figma 设计（如有引用）：

   Figma 设计链接可能出现在两个位置：工单字段中的直接 URL，或通过 Figma for Jira 应用（“添加设计”按钮）设置的关联设计。请检查这两个来源。

   a) 检查工单字段中的 Figma URL：

   • 搜索所有工单字段（描述、评论、附件、自定义字段），查找 Figma URL（例如，https://www.figma.com/design/...、https://www.figma.com/file/...、https://www.figma.com/proto/...） b) 通过 Atlassian GraphQL API 检查关联设计：

   • 通过“添加设计”按钮添加的 Figma 设计不会存储在标准工单字段、远程链接或附件中。它们存储为关联设计——这是一个独立的数据层，只能通过带基本身份验证的 Atlassian GraphQL API 访问。

   • OAuth 令牌（来自 acli）无法用于此查询——designs 字段仅限 Atlassian 自有客户端访问。通过租户端点使用个人 API 令牌进行基本身份验证，会被视为 Atlassian 自有客户端。

   • 获取凭据：

     • 检查 ATLASSIAN_EMAIL 和 ATLASSIAN_TOKEN 环境变量
     • 如果其中任何一个缺失，使用 AskUserQuestion 请求用户提供：

       要检索与此工单关联的 Figma 设计，我需要你的 Atlassian 凭据（基本身份验证，不是 OAuth）。

       • 邮箱：你的 Atlassian 账户邮箱
       • API 令牌：从 https://id.atlassian.com/manage/api-tokens 获取的个人 API 令牌

       你也可以设置 ATLASSIAN_EMAIL 和 ATLASSIAN_TOKEN 环境变量，以便今后跳过此步骤。

   • 获取工单的数字 ID：

     • 从 acli jira workitem view <JIRA-ID> --json 响应（已在步骤 3 中获取）中提取数字 id 字段（不是工单键，例如 150983，而不是 PROJ-123）

   • 查询 GraphQL API：

     CLOUD_ID="d5b2094b-04bb-467d-b98e-f39df372f11b"
     ISSUE_ID="<numeric-id>"
     ISSUE_ARI="ari:cloud:jira:${CLOUD_ID}:issue/${ISSUE_ID}"
     SITE_ARI="ari:cloud:jira::site/${CLOUD_ID}"
     curl -s -u "${ATLASSIAN_EMAIL}:${ATLASSIAN_TOKEN}" \
       -X POST \
       -H "Content-Type: application/json" \
       -H "X-Query-Context: ${SITE_ARI}" \
       "https://tablecheck.atlassian.net/gateway/api/graphql" \
       -d "{
         \"query\": \"query GetDesigns { jira_issuesByIds(ids: [\\\"${ISSUE_ARI}\\\"]) { key designs @optIn(to: \\\"GraphStoreIssueAssociatedDesign\\\") { edges { node { ... on DevOpsDesign { displayName designUrl: url } } } } } }\"
       }"
     

   • 从响应中提取所有 designUrl 值——这些就是 Figma URL

   • 如果 GraphQL 调用失败（例如身份验证问题、未找到设计等），继续处理其余信息——尽力检索即可

   c) 使用 fcli 提取设计信息：

   • 如果从任一来源（步骤 4a 或 4b）找到 Figma URL：

     1. 验证 fcli 是否可用：

        • 运行 fcli auth status，检查 CLI 是否已安装并完成身份验证
        • 如果找不到 fcli，向开发者显示 Figma URL，并使用 AskUserQuestion 请求其手动提供设计资源（PNG/SVG 文件），然后继续
        • 如果 fcli 尚未完成身份验证，若有 FIGMA_ACCESS_TOKEN 环境变量，则尝试设置；否则告知开发者，并改为请求其手动提供资源

     2. 提取每个 Figma URL 的设计数据：

        文件元数据：

        fcli file info --url "<FIGMA_URL>" --json
        

        获取文件名、上次修改日期和版本信息。

        文档树（结构和布局）：

        fcli file inspect --url "<FIGMA_URL>" --depth 5
        

        返回可读的树状结构，展示组件层级：TYPE name [id]，每一级缩进 2 个空格。使用 --depth 控制树的深度（完整文件的默认值为 3）。对于特定节点（URL 带有 node-id 参数），默认深度不受限制。

        如需完整的结构细节（以了解具体属性、约束和自动布局设置）：

        fcli file inspect --url "<FIGMA_URL>" --depth 5 --json
        

        导出截图：

        mkdir -p /tmp/<JIRA-ID>-figma
        fcli file export --url "<FIGMA_URL>" --scale 2 --output /tmp/<JIRA-ID>-figma/
        

        将 URL 中引用的节点导出为 PNG 文件（默认格式）。如果 URL 包含 node-id 查询参数，则导出该特定节点。使用 --ids 导出多个节点：--ids "1:2,3:4"。输出文件命名为 {node-id}.png（冒号替换为连字符）。

        列出组件（如果文件是组件库或包含可复用组件）：

        fcli components list --url "<FIGMA_URL>" --json
        

        返回组件名称、节点 ID 和描述，有助于将 Figma 组件映射到代码库中的组件。

        列出样式（颜色、排版、效果）：

        fcli styles list --url "<FIGMA_URL>" --json
        

        返回样式名称、类型（FILL、TEXT、EFFECT、GRID）和节点 ID。

     3. 分析提取的设计数据：

        • 阅读导出的 PNG 截图，了解视觉设计（布局、间距、颜色、排版、组件结构、交互状态）
        • 使用文档树了解组件层级和命名
        • 使用组件和样式列表，将设计令牌映射到现有代码库模式
        • 注意：fcli 使用 --url，以避免 Figma URL 中的 ? 和 & 导致的 shell 引号问题

     4. 存储设计数据 — 树结构、截图路径、组件和样式将传递给 PO、设计师、测试规划师和开发 Agent

   • 如果两个来源都未找到 Figma URL，则静默跳过此步骤

5. 确定常规提交前缀：

   • 根据所有可用的工单字段（问题类型、摘要、描述、自定义字段等），推断最合适的常规提交前缀：
     • feat — 新功能或特性
     • fix — 修复缺陷
     • docs — 仅修改文档
     • style — 代码风格修改（格式、空白等）
     • refactor — 重构代码，不改变行为
     • perf — 性能改进
     • test — 仅添加或更新测试
     • build — 构建系统或依赖项修改
     • ci — CI/CD 配置修改
     • chore — 维护任务、工具等
     • revert — 撤销之前的修改
   • 将问题类型作为主要判断依据（例如，Bug -> fix，包含新功能的 Story -> feat）
   • 当问题类型不明确时，根据摘要和描述进一步判断（例如，Task 可能对应 refactor、chore、docs 等）
   • 如果分支名称已包含常规提交前缀（例如，fix/PROJ-123），可将其作为参考，但需根据工单内容确认是否合理
   • 如果无法确定应使用哪个前缀，请使用 AskUserQuestion 让开发者选择。列出最合适的候选项，并简要说明各自适用的原因。

6. 分析代码库：

   • 全面阅读所有可用的工单字段，包括摘要、描述、评论和任何自定义字段（预期/实际行为、验收标准、复现步骤等）。
   • 将步骤 3 中下载的附件纳入分析（例如，使用屏幕截图了解 UI 预期，使用日志识别错误模式，使用模型稿指导实现，使用数据文件了解预期输入/输出）。
   • 探索代码库，了解：
     • 与工单相关的文件和模块
     • 受影响区域中现有的模式和约定
     • 已有的相关单元测试或需要更新的单元测试
     • e2e 测试设置：查找 Playwright 配置（playwright.config.ts）、现有的 e2e 测试文件、测试目录结构、身份验证模式（storage state、全局设置）和辅助工具
   • 将 Conventional Commits 前缀作为预期工作类型的参考（例如，fix 表示修复错误，feat 表示新增功能，refactor 表示重构）

7. 评估是否应拆分工单（仅在必要时）：

   分析工单和代码库后，评估这项工作对于单个 PR 来说是否过于庞大。PR 应尽可能小，并且能够独立测试。只有满足以下至少一个条件时，才建议拆分：

   • 改动过多： 实现会涉及多个区域中的大量文件，导致 PR 难以审查且合并风险较高
   • 关注点彼此独立： 工单涉及应用中互不相关的部分（例如，后端 API + 前端 UI + 数据库迁移），且每部分都可以独立交付和测试
   • 工作类型混杂： 工单包含本质上不同类型的改动（例如，为实现某项功能而进行的重构，或将错误修复与新功能捆绑在一起）
   • 存在先后依赖： 必须先合并部分改动，才能开始其余工作（例如，其他部分所依赖的共享工具或数据模型改动）

   如果需要拆分，使用 AskUserQuestion 向开发者提出拆分方案：

   这张工单的工作量似乎较大，拆分为更小、可独立审查的 PR 会更合适。

   建议拆分方案：

   1. <简短标题> — <此部分涵盖的内容及其独立性说明>
   2. <简短标题> — <此部分涵盖的内容>
   3. ...

   是否要拆分这张工单？

   • “Yes — split”：使用 Atlassian CLI 在当前工单下创建子任务。然后本次会话只处理第一部分，其余部分将在之后的会话中处理。

     acli jira workitem create --from-json <temp-file.json> --json
     

     每个子任务的负载应包含：

     {
       "project": "<project-key>",
       "type": "Sub-task",
       "summary": "<chunk title>",
       "parent": "<JIRA-ID>",
       "description": { ... ADF description of the chunk scope ... }
     }
     

     创建子任务后，告知开发者本次将处理哪一部分，并列出已创建的子任务 ID。
   • “No — keep as one”：将整张工单作为单个 PR 继续处理。

   如果不需要拆分（工单较小、目标明确或只涉及一个区域），请静默跳过此步骤，不要提及拆分。

8. 维护 Epic 背景记录文件：

   启动 PO 前，检查当前工单是否属于某个父级 Epic，并维护一份记录 Epic 及其子工单累积背景信息的背景记录文件。 a) 确认父级史诗：

   • 查看步骤 3 获取的工单字段，查找父级史诗链接（例如 Epic Link 字段、parent 字段，或任何引用史诗的字段）。
   • 如果工单有父级史诗，请使用 Atlassian CLI 获取该史诗的摘要、描述和验收标准：

     acli jira workitem view <EPIC-KEY> --fields summary,description,acceptance-criteria --json
     

   • 如果工单没有父级史诗，则完全跳过此步骤。

   b) 检查是否已有项目背景文件：

   • 查找项目根目录下是否有 lore/ 目录。
   • 检查此史诗是否已有项目背景文件。文件应以史诗键命名：lore/<EPIC-KEY>.md（例如 lore/PROJ-42.md）。

   c) 创建或更新项目背景文件：

   • 如果不存在 lore/ 目录，则创建该目录。
   • 如果此史诗尚无项目背景文件，则按以下结构创建 lore/<EPIC-KEY>.md：

     # <EPIC-KEY>: <Epic Summary>
     
     ## Epic Description
     <Epic description and acceptance criteria from the epic ticket>
     
     ## Tickets
     
     ### <JIRA-ID>: <Ticket Summary>
     - **Type:** <issue-type> | **Priority:** <priority>
     - **Description:** <Brief summary of the ticket>
     - **Acceptance Criteria:** <Key acceptance criteria>
     

   • 如果此史诗已有项目背景文件，则在 ## Tickets 部分下为当前工单追加新条目：

     ### <JIRA-ID>: <Ticket Summary>
     - **Type:** <issue-type> | **Priority:** <priority>
     - **Description:** <Brief summary of the ticket>
     - **Acceptance Criteria:** <Key acceptance criteria>
     

   • 项目背景文件是一份持续完善的文档，会随着史诗中的工单逐步积累上下文。每条工单记录都应简洁明了，同时包含足够的信息，以便理解该工单在整个史诗中的作用。

阶段 2 — 产品负责人：需求与验收标准

9. 启动产品负责人 Agent：

   使用 Task 工具启动 PO Agent。该 Agent 负责根据阶段 1 收集的所有上下文撰写需求和验收标准。PO Agent 不会实现任何内容——它只会生成一份需求文档。

   a) 准备 PO 提示词：

   • 将目前收集的所有上下文传递给 PO Agent：
     • 完整的 JIRA 工单内容（摘要、描述、所有字段和评论）
     • 步骤 3 下载的附件文件路径（以便 PO 查看图片获取视觉上下文，并读取文本文件中的数据和需求）
     • Figma 设计数据（如果有获取）
     • 步骤 5 确定的常规提交前缀
     • 步骤 6 的代码库分析（相关文件、模式、约定和测试设置）
     • 项目背景文件内容（如果有）
   • 指示 PO Agent 按以下结构生成需求文档：

   ## Ticket: <JIRA-ID>
   **<Summary>**
   Type: <issue-type> | Priority: <priority> | Commit prefix: <conventional-commit-prefix>
   
   ### Understanding
   <Brief summary of what the ticket is asking for, synthesized from the description, comments, and Figma designs. Call out any ambiguities or conflicting information.>
   
   ### Requirements
   1. <Requirement 1 — clear, testable statement of what the implementation must do>
   2. <Requirement 2>
   3. ...
   
   ### Acceptance Criteria
   - [ ] <Criterion 1 — specific, verifiable condition that must be true when done>
   - [ ] <Criterion 2>
   - [ ] ...
   
   ### Design Needs
   - <Whether this ticket requires design work: Yes / No>
   - <If yes, what aspects need design: UI layout, component design, interaction patterns, etc.>
   - <If Figma designs are provided, note which aspects are already covered and which need further design work>
   
   ### Implementation Plan
   1. <Step 1 — what to do and which files to touch>
   2. <Step 2>
   3. ...
   
   ### Files to Modify
   - `path/to/file.ts` — <what changes are needed>
   - `path/to/other.ts` — <what changes are needed>
   
   ### New Files
   - `path/to/new-file.ts` — <purpose>
   (or "None" if no new files are needed)
   
   ### Unit Tests
   - <Which unit test files to update or create>
   - <What scenarios to cover>
   
   ### E2E Tests
   - <Which e2e test files to update or create>
   - <User flows to cover: describe each flow as a sequence of actions and expected outcomes>
   - <Authentication requirements for the test scenarios>
   (or "None — changes are not user-facing" if e2e tests are not applicable)
   
   ### Risks / Open Questions
   - <Any uncertainties, assumptions, or things to clarify with the team>
   

   b) 端到端测试规划指南（纳入 PO 提示词）：

   • 对任何面向用户的更改编写端到端测试，例如新增页面、新增 UI 流程、修改交互、表单提交、导航变更等。
   • 遵循项目现有的端到端测试约定：文件命名、目录结构、身份验证方式、辅助工具和断言模式。
   • 每项端到端测试都应覆盖完整的用户流程（例如：“导航至设置，修改个人资料名称并保存，验证成功提示和更新后的名称”）。
   • 对于缺陷修复，添加端到端测试，复现原始缺陷场景并验证问题已解决。
   • 如果项目没有端到端测试设置，请注明这一点，并建议将其作为实现的一部分进行配置。
   • 仅对非面向用户的更改跳过端到端测试（例如，不改变行为的纯重构、CI 配置或构建工具）。

   c) 等待 PO Agent 完成并收集其需求文档。

10. 批准需求：

    如果 headless = false（默认）： 向开发者展示 PO 的需求文档，并使用 AskUserQuestion 征求确认：

    产品负责人已准备好以下需求和验收标准。是否要继续？

    • 批准 — 接受需求，进入阶段 3
    • 请求修改 — 开发者提供需要调整的反馈
    • 拒绝 — 完全停止技能执行

    如果选择“请求修改”：

    • 使用 AskUserQuestion 收集开发者的反馈
    • 使用原始上下文和开发者的反馈重新启动 PO Agent，请其修改需求
    • 再次呈现修改后的需求以供批准
    • 重复以上步骤，直到开发者批准或拒绝

    在开发者明确批准之前，不要进入阶段 3。

    ---

    如果 headless = true：

    不要征求开发者的意见，而是启动一个审查者 Agent来审查 PO 的需求。审查者将作为严谨的第二双眼睛。

    a) 启动审查者 Agent，并提供：

    • PO 的需求文档
    • 阶段 1 的所有上下文（工单内容、代码库分析、附件、Figma 数据、背景信息）
    • 以下指示：“你是一名审查需求文档的资深工程师。你的任务是找出缺漏、歧义、遗漏的边缘情况、错误假设或过度设计。请简洁具体地说明。对于每个问题，指出问题所在并提出修复建议。如果需求没有问题，请明确说明。”

    **b) 收集审查者的发现。**如果审查者发现问题：

    • 使用原始上下文和审查者的反馈重新启动 PO Agent，请其修改
    • 负责人 Agent（你）同时阅读修改后的需求和审查者最初指出的问题，然后判断修改是否充分解决了这些问题
    • 如果修改后的需求令人满意，则批准并继续
    • 如果一轮修改后仍存在关键问题，再进行一轮修改（最多 2 轮），然后批准最佳版本，并在最终报告中注明任何尚未解决的问题

    c) 如果审查者未发现问题，立即批准需求并继续。

阶段 3 — 实施团队（TDD）

团队遵循严格的测试驱动开发工作流：先提出并批准测试，再编写任何代码；随后编写测试并确认测试失败（红），最后才编写生产代码使测试通过（绿）。

11. 确定团队组成：

    根据已批准的需求，决定要启动哪些 Agent。团队始终包括测试编写人员和开发人员；设计师则视情况而定。

    a) 设计师 — 视情况而定：

    • 如果需求中的“设计需求”部分为否：完全跳过设计师
    • 如果需求为是，且已提供 Figma 设计（步骤 4）：启动 1 名设计师 Agent
    • 如果需求为是，且没有可用的 Figma 设计：启动 2 名设计师 Agent

    **b) 测试编写人员：**始终启动 1–2 名测试编写人员 Agent（在任何生产代码存在之前编写测试）

    **c) 开发人员：**始终启动 2–3 名开发人员 Agent（编写生产代码以通过测试）

12. 启动设计师 Agent（如需要）：

    如果需要设计师，先启动他们，并等待他们完成后再继续制定测试计划。 如果有 1 位设计师（已提供设计资源）：

    • 使用 Task 工具启动 1 个设计师 Agent
    • 设计师的工作是：
      • 分析开发者在第 4 步提供的 PNG/SVG 设计资源
      • 将设计中的视觉组件映射到代码库中已有的组件
      • 编写设计实现指南：应使用哪些组件、间距、颜色、排版、响应式行为和交互状态
      • 找出设计资源与需求之间的差异
    • 向该 Agent 提供：已批准的需求、设计资源文件路径（以便其读取/查看）以及代码库分析（现有组件、设计系统、样式模式）

    如果有 2 位设计师（没有 Figma）：

    • 使用 Task 工具并设置 run_in_background: true，并行启动 2 个设计师 Agent
    • 设计师 1 — 调研： 探索现有代码库中的设计模式、组件库、设计令牌和样式约定。记录当前使用的设计系统。
    • 设计师 2 — 提案： 根据需求和现有设计模式（获取后共享设计师 1 的发现），提出 UI/UX 方案：组件结构、布局、交互和视觉设计决策。
    • 等待两者完成，并将其输出整合为开发者使用的设计指南。

    将设计指南作为额外上下文传递给后续 Agent。

13. 提出测试计划：

    使用 Task 工具启动 1 个测试规划 Agent。此 Agent 不会编写测试代码，而是列出用于验证预期行为的完整测试清单。

    a）向测试规划 Agent 提供：

    • 完整的已批准需求和验收标准
    • 实现计划（要修改的文件、新建的文件、预期行为）
    • 代码库分析（现有测试文件、测试框架、约定、目录结构）
    • 第 3 步下载的附件文件路径（以便规划者在设计测试场景时参考屏幕截图、数据文件或日志）
    • 设计指南（如果设计师编写了指南）
    • Epic 背景文件内容（如果有），以便规划者了解有哪些相关工单，以及未来任务计划实现哪些行为

    b）测试规划者必须制定结构化的测试计划：

    ## Test Plan
    
    ### Unit Tests
    
    #### <test-file-path> (new / existing)
    - `<test name>` — <what it verifies, expected input → expected output>
    - `<test name>` — <what it verifies>
    ...
    
    #### <another-test-file-path> (new / existing)
    - `<test name>` — <what it verifies>
    ...
    
    ### E2E Tests
    
    #### <e2e-test-file-path> (new / existing)
    - `<test name>` — <user flow: step-by-step actions and expected outcomes>
    ...
    
    (or "None — changes are not user-facing" if e2e tests are not applicable)
    
    ### Coverage Summary
    - Total unit tests: <N>
    - Total e2e tests: <N>
    - Acceptance criteria covered: <list which criteria each test addresses>
    - Edge cases covered: <list edge cases>
    

    c）测试计划指南：

    • 每项验收标准都必须至少由一个测试覆盖
    • 包含边缘情况、错误路径和边界条件
    • 对于错误修复，包含一个能够复现原始错误的测试
    • 遵循项目现有的测试命名约定和文件结构
    • 单元测试应聚焦，每个测试只验证一种行为
    • E2E 测试应覆盖完整的用户流程
    • 指明需要更新哪些现有测试文件（而不仅是新增测试）
    • **本地化：**切勿断言翻译后的字符串（例如，"Submit"、"Enregistrer"）。始终断言翻译键（例如，"common.submit"），以免测试因翻译变更或在不同区域设置下运行而失败
    • **不得测试中间状态：**不要编写断言临时状态的测试；这种状态仅仅是因为后续任务尚未实现才存在。测试必须验证整个史诗最终状态下正确的行为，而不只是当前任务的行为。结合史诗背景和相关任务理解完整情况。例如，如果一个史诗要创建一个标签为 "Hello" 的按钮，并拆分为任务 A（“创建按钮”）和任务 B（“添加标签”），任务 A 绝不能包含断言按钮没有文本的测试——任务 B 实现后，该断言就会失败。相反，任务 A 应测试它新增的内容（按钮存在、可点击等），并将标签测试留给任务 B。

14. 批准测试计划：

    如果 headless = false（默认）：

    向开发者展示测试规划器制定的完整测试计划，并使用 AskUserQuestion：

    团队已准备好以下测试计划。请审核拟议的测试。 您要继续执行这些测试吗？

    • 批准 — 接受测试计划，继续执行步骤 15
    • 请求修改 — 开发者提供需要添加、删除或修改的反馈
    • 拒绝 — 完全停止技能执行

    如果选择“请求修改”：

    • 使用 AskUserQuestion 收集开发者的反馈
    • 根据原始上下文和开发者的反馈，重新启动测试规划器 Agent，并要求其修订测试计划
    • 再次提交修订后的测试计划以供批准
    • 重复此过程，直到开发者批准或拒绝

    在开发者明确批准测试计划之前，不得继续执行步骤 15。

    ---

    如果 headless = true：

    不询问开发者，而是启动审核者 Agent来审查测试计划。

    a）启动审核者 Agent，并提供：

    • 测试规划器制定的完整测试计划
    • 已批准的需求和验收标准
    • 代码库分析（现有测试、约定、框架）
    • 指令：“你是一名资深 QA 工程师，负责审核测试计划。请检查：验收标准是否存在覆盖遗漏、测试是否冗余或相互重叠、是否遗漏边缘情况和错误路径、测试场景是否不切实际，以及测试是否断言中间状态而非最终行为。请简洁、具体地指出问题。对于每个问题，说明具体错误并提出修复建议。如果计划没有问题，请明确说明。”

    **b）收集审核者的发现。**如果审核者指出问题：

    • 根据原始上下文和审核者的反馈，重新启动测试规划器 Agent，并要求其修订测试计划
    • 主 Agent（即你）同时阅读修订后的测试计划和审核者最初提出的问题，然后判断修订是否充分解决了这些问题
    • 如果修订后的计划令人满意，则批准并继续
    • 如果经过一轮修订后仍存在严重问题，再进行一轮修订（最多 2 轮），然后批准最佳版本，并在最终报告中注明尚未解决的问题

    c）如果审核者未发现问题，立即批准测试计划并继续。

15. 实现测试（TDD 红灯阶段）： 使用 Task 工具生成 1–2 个测试编写 Agent，并设置 run_in_background: true。这些 Agent 根据已批准的测试计划编写实际测试代码。此阶段不得编写生产代码。

    a) 向每个测试编写 Agent 提供：

    • 已批准的测试计划（要实现的确切测试清单）
    • 完整的已批准需求和验收标准
    • 项目的测试设置、约定、现有测试文件和辅助工具
    • 第 3 步下载的附件文件路径（测试编写者可能需要截图来进行视觉回归测试，或需要数据文件作为测试固件）
    • 设计指南（如果设计师提供了）
    • 明确指示：仅编写测试代码——不得编写或修改任何生产代码
    • 对于单元测试：编写导入将要创建或修改的模块/函数的测试，并断言预期行为
    • 对于端到端测试：编写执行用户操作并断言预期结果的测试
    • **本地化：**切勿断言翻译后的/本地化的字符串。始终断言翻译键，以确保测试不依赖语言区域设置，并且翻译变更不会导致测试失败

    b) 在 Agent 之间分配测试工作：

    • 按测试类型分配：一个 Agent 负责单元测试，另一个负责端到端测试
    • 或按功能领域分配：每个 Agent 负责特定领域的所有测试（单元测试 + 端到端测试）
    • 对于简单的工单，1 个测试编写 Agent 即可

    c) 等待所有测试编写 Agent 完成。

    d) 验证测试编写正确：

    • 运行测试，确认测试因预期原因失败（缺少实现），而不是因语法错误或表明测试代码有问题的导入失败而失败
    • 如果测试因测试代码错误（语法、导入错误、设置不正确）而失败，请先修复测试代码，再继续
    • 目标是：测试在语法上正确、结构合理，但由于其测试的生产代码尚不存在或尚未实现预期行为而失败

16. 实现生产代码（TDD 绿色阶段）：

    使用 Task 工具生成 2–3 个开发 Agent，并设置 run_in_background: true。他们的唯一目标是编写生产代码，使之前编写的所有测试通过。

    a) 分配工作：

    • 分析已批准的实现计划，并按独立性对步骤进行分组——涉及不同文件或不重叠代码区域的步骤可以并行执行
    • 常见的分工策略：
      • 按功能领域分配（例如，一个 Agent 负责 API 变更，另一个负责 UI）
      • 按层分配（例如，一个 Agent 负责后端，另一个负责前端）
      • 按文件组分配（例如，一个 Agent 修改现有文件，另一个创建新文件）
    • 对于不适合并行处理的简单工单（例如单文件变更），安排 2 个 Agent 即可——一个负责实现，另一个负责审查和协助
    • 如果步骤之间存在依赖关系（例如一项变更需要另一项先完成），请注明，并让依赖方等待

    b) 向每个开发 Agent 提供：

    • 完整的已批准需求和验收标准
    • 第 15 步编写的测试文件（以便开发者准确了解测试的预期）
    • 实现计划中分配给他们的具体步骤
    • 相关文件路径及所需变更
    • 在代码库中观察到的编码约定和模式（来自第 6 步）
    • 第 3 步下载的附件文件路径（开发者可能需要截图作为 UI 参考，或需要数据文件作为实现背景）
    • 设计指南（如果设计师提供了）
    • 指示其遵循现有项目模式，除非计划另有规定，否则不得引入新的依赖或抽象
    • 明确指示：不得修改任何测试文件——只编写生产代码，让现有测试通过

    c) 等待所有开发 Agent 完成。 d) 合并并验证：

    • 检查各 Agent 的更改是否存在冲突（两个 Agent 修改了同一个文件）
    • 如果存在冲突，阅读双方的更改并妥善合并
    • 快速进行健全性检查：确保应用所有更改后，代码库可以编译并通过 lint 检查

17. 验证所有测试均通过：

    运行完整的测试套件（单元测试 + 端到端测试，如适用），确认全部通过。

    a) 如果测试失败，分析失败原因：

    • 如果失败是因为生产代码有误，则再启动 1 个开发者 Agent 修复生产代码（而非测试——测试定义了预期行为）
    • 如果失败是因为测试本身确实存在缺陷（例如断言不稳定，或设置与已批准的测试计划不符），则修复测试代码

    b) 如果修复后测试仍然失败，则向开发者报告剩余的失败项

    c) 确保未涉及此次更改的现有测试仍然通过，避免回归问题

Phase 4 — 建议更新 JIRA 工单

18. 根据需求和验收标准建议修改工单：

    团队完成工作后，根据执行此技能期间编写的需求和验收标准，建议改进原始 JIRA 工单。

    a) 分析差距：

    • 重新阅读原始工单描述（第 3 步）
    • 将其与 PO 批准的需求和验收标准（第 9 步）进行比较
    • 找出工单中缺失的内容：
      • PO 编写但未包含在原始工单中的验收标准
      • PO 阶段澄清或扩展的需求
      • 设计人员作出的设计决策（如适用）
      • 关于所采用方案的技术说明

    b) 起草改进后的描述：

    • 编写修订后的工单描述，纳入需求和验收标准
    • 保留所有有用的原始内容（背景、说明、链接、参考资料）
    • 添加或改进：
      • 清晰的问题陈述或功能原因
      • PO 文档中的验收标准
      • 关于所采用方案的技术说明（简要说明，提供足够信息以供后续读者了解）
      • 受影响的文件/区域（概括说明，例如“身份验证模块”“设置页面”）
    • 保持与项目现有工单描述一致的语气

    c) 向开发者展示：

    • 以清晰的前后对比格式展示建议的描述：

      ## 建议的工单描述更新
      
      ### 当前描述
      > <原始描述；如果没有，则写“（空）”
      
      ### 建议描述
      <新描述>
      
      ### 更改内容
      - <主要差异的项目列表>
      

    • 使用 AskUserQuestion 向开发者询问：

      是否要使用建议的改进内容更新 JIRA 工单描述？

    • 选项：是 — 更新工单、否 — 跳过

    d) 更新工单（如获批准）：

    • 如果开发者批准，则将描述写为 ADF JSON 负载，并使用 --from-json 更新（见下文的 ADF 格式参考）：

      acli jira workitem edit --from-json <temp-file.json> --yes
      

      JSON 文件必须包含完整的编辑负载，描述须为 ADF 对象：

      {
        "issues": ["<JIRA-ID>"],
        "description": {
          "version": 1,
          "type": "doc",
          "content": [ ... ADF 节点 ... ]
        }
      }
      

    • 确认更新成功：

      工单 <JIRA-ID> 的描述已更新。
      

    • 如果更新失败，则显示错误，并提供可复制的建议描述文本，以便开发者手动更新

19. 最终报告：

    向开发者提供一份全面的总结：

    ## 工单已完成：<JIRA-ID>
    **<总结>**
    ### 团队
    - PO：已编写需求和验收标准
    - 设计师：<N>（或“无 — 无需设计工作”）
    - 测试编写者：<N>（在实现前编写了测试）
    - 开发者：<N>（编写了可通过测试的生产代码）
    
    ### 实现
    - 修改的文件：<N>
    - 新增的文件：<N>
    - 变更行数：+<新增> / -<删除>
    
    ### 测试
    - 单元测试：<N> 项通过
    - E2E 测试：<N> 项通过（或“N/A”）
    - 是否需要修复测试：<是/否 — 修复了几轮>
    
    ### 验收标准
    - [x] <标准 1>
    - [x] <标准 2>
    - ...
    
    ### JIRA 工单
    - 是否已更新描述：<是/否>
    
    ### 后续步骤
    - <任何剩余的手动步骤，例如“运行数据库迁移”“更新环境变量”>
    - <任何需要人工判断的问题>
    

20. 处理边缘情况：

    • 如果工单描述为空，请注明，并让 PO 仅根据摘要和评论制定需求
    • 如果没有评论，请在分析中跳过该部分
    • 如果代码库探索发现工单可能已处理，请在创建 PO 前告知开发者
    • 如果工单描述过于模糊，PO 应列出已理解的内容，并标记待解决的问题，以便开发者在审批阶段回答
    • 如果项目没有测试框架，请注明并跳过 TDD 阶段（步骤 13–17）——直接创建开发者来实现代码
    • 如果设计师 Agent 给出相互冲突的建议，请同时呈现给开发者，由他们选择
    • 如果开发者 Agent 对同一文件做出了相互冲突的更改，请在运行测试套件前解决冲突
    • 如果绿色阶段和修复循环（修复 -> 失败 -> 修复 -> 失败）后测试仍然失败，请在 2 次尝试后停止，并向开发者报告剩余失败项
    • 如果测试规划者生成的测试无法在没有生产代码脚手架（例如类型定义、接口）的情况下编写，请注明这一点，并让测试编写者创建最小类型桩，而不是实现代码

---

ADF 格式参考

JIRA 不会渲染 Markdown。描述必须使用 Atlassian Document Format（ADF）——一种基于 JSON 的文档格式。--description-file 标志会将文件内容视为纯文本字符串，因此不能用于富文本描述。请改用 --from-json。

重要：--from-json 需要一个包含完整编辑载荷的结构化 JSON 文件。description 字段必须是 ADF 对象，而不是字符串。你可以运行 acli jira workitem edit --generate-json 查看预期的架构。

编辑载荷格式（--from-json）：

{
  "issues": ["<JIRA-ID>"],
  "description": {
    "version": 1,
    "type": "doc",
    "content": [
      {
        "type": "heading",
        "attrs": { "level": 2 },
        "content": [{ "type": "text", "text": "Description" }]
      },
      {
        "type": "paragraph",
        "content": [{ "type": "text", "text": "What was implemented." }]
      },
      {
        "type": "heading",
        "attrs": { "level": 2 },
        "content": [{ "type": "text", "text": "Acceptance Criteria" }]
      },
      {
        "type": "taskList",
        "attrs": { "localId": "ac-list" },
        "content": [
          {
            "type": "taskItem",
            "attrs": { "localId": "ac-1", "state": "TODO" },
            "content": [{ "type": "text", "text": "First criterion" }]
          }
        ]
      }
    ]
  }
}

常见 ADF 节点类型：

Markdown	ADF type	说明
## Heading	带有 attrs.level 的 heading	级别 1–6
纯文本	带有 text 子节点的 paragraph
**bold**	带有 marks: [{"type": "strong"}] 的 text
*italic*	带有 marks: [{"type": "em"}] 的 text
- item	bulletList > listItem > paragraph
1. item	orderedList > listItem > paragraph
- [ ] task	taskList > taskItem（状态：TODO/DONE）
`code`	带有 marks: [{"type": "code"}] 的 text	行内代码
代码块	带有 attrs.language 的 codeBlock
---	rule	水平分隔线
[link](url)	带有 marks: [{"type": "link", "attrs": {"href": "url"}}] 的 text