ticket-craft

Ticket Craft 技能

编写 AI Agent 可自主执行的软件工单。

用途： 定义一种工单格式，将软件工程最佳实践（INVEST、Given-When-Then、Definition of Ready）与 Claude Code 特定的上下文要求相结合。使用此技能创建的每张工单都是“Claude Code Ready”——这意味着 Agent 可以直接接手并执行，无需询问澄清问题。

适用范围： Jira、Asana、Linear、GitHub Issues 或任何工单系统。

---

核心原则

┌─────────────────────────────────────────────────────────────────┐
│  A TICKET IS A PROMPT                                            │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  Traditional tickets are written for humans who can:             │
│  - Ask clarifying questions in Slack                             │
│  - Draw on institutional knowledge                               │
│  - Infer intent from vague descriptions                          │
│                                                                  │
│  AI agents cannot do any of this.                                │
│                                                                  │
│  Every ticket must be SELF-CONTAINED:                            │
│  - Explicit file references (not "the auth module")              │
│  - Pattern references (not "follow our conventions")             │
│  - Verification criteria (not "make sure it works")              │
│  - Constraints (not just what to do, but what NOT to do)         │
│  - Test commands (not "run the tests")                           │
│                                                                  │
│  If Claude Code can execute it without asking a question,        │
│  the ticket is ready. If it can't, it's not.                     │
└─────────────────────────────────────────────────────────────────┘

---

INVEST+C 标准

标准 INVEST 加上 C，代表 Claude-Ready：

标准	问题	不符合的情况……
I - 独立	是否可以不等待其他工单就完成？	受未记录的依赖项阻塞
N - 可协商	实现方式是否留有调整空间？	对实现细节规定过多
V - 有价值	能否说清楚谁会受益，以及如何受益？	没有明确的用户或业务价值
E - 可估算	团队是否掌握足够信息来评估工作量？	太模糊或规模太大，无法估算
S - 小型	一个人能否在 1-3 天内完成？	验收标准超过 5 条
T - 可测试	能否编写通过/失败测试？	使用“快速”或“良好的 UX”等模糊表述
C - Claude-Ready	AI Agent 能否在无需澄清问题的情况下执行？	缺少文件引用、模式、验证方式或约束

---

工单类型

1. 功能工单

## [PROJ-XXX] {Verb} {Feature} for {User}

**Type:** Feature
**Priority:** {Critical | High | Medium | Low}
**Points:** {1 | 2 | 3 | 5 | 8}
**Labels:** {frontend, backend, api, database, etc.}
**Epic:** {Parent epic}

---

### User Story
As a {specific persona},
I want to {specific action},
so that {measurable benefit}.

### Background
{1-2 paragraphs on why this matters. Link to product brief, user research,
or business justification. Include any relevant metrics or user feedback.}

### Acceptance Criteria

**AC1: {Happy path scenario}**
Given {precondition},
when {action},
then {expected result}.

**AC2: {Edge case / error scenario}**
Given {precondition},
when {action},
then {expected result}.

**AC3: {Boundary condition}**
Given {precondition},
when {action},
then {expected result}.

### Out of Scope
- {Explicitly state what this ticket does NOT include}
- {Prevents scope creep and keeps ticket small}

---

### Claude Code Context

#### Relevant Files (read these first)
- `src/services/example.ts` - Existing service to extend
- `src/models/example.ts` - Data model definition
- `src/api/routes/example.ts` - Existing endpoint patterns to follow

#### Pattern Reference
Follow the pattern in `src/services/user.ts` for service layer implementation.
Follow the pattern in `src/api/routes/users.ts` for route definition.
Follow the pattern in `tests/services/user.test.ts` for test structure.

#### Database Changes
- {Table to create/modify, columns, types}
- {Migration file location: `supabase/migrations/` or `prisma/migrations/`}
- {RLS policies if using Supabase}

#### API Contract

POST /api/{resource} Request: { field1: string, field2: number } Response: { id: string, field1: string, created_at: string } Error: { error: string, code: number }

#### Constraints
- Do NOT modify {specific files or modules}
- Do NOT add new dependencies without approval
- Follow existing error handling in `src/core/exceptions.ts`
- {Any performance budgets: response time < 200ms, bundle size < 50KB}

#### Verification
```bash
# Run specific tests
npm test -- --grep "{feature name}"

# Lint check
npm run lint

# Type check
npm run typecheck

# Full validation
npm test -- --coverage

环境变量

• 已有：{列出 .env 中相关的现有变量}
• 新增必需项：{列出所需的任何新变量}

---

依赖项

• 被以下工单阻塞：{PROJ-XXX}（{简要说明}）
• 阻塞以下工单：{PROJ-YYY}（{简要说明}）

设计

• 样稿：{适用时填写 Figma/设计链接}

---

### 2. Bug Ticket

```markdown
## [BUG-XXX] Fix: {Component} - {Symptom}

**Type:** Bug
**Priority:** {Critical | High | Medium | Low}
**Points:** {1 | 2 | 3 | 5}
**Labels:** {regression, ux-bug, data-bug, security-bug}
**Severity:** {Blocks users | Degrades experience | Cosmetic}

---

### Bug Summary
{One sentence: what is broken and who is affected.}

### Environment
- Browser/OS: {e.g., Chrome 120 / macOS 14.2}
- Environment: {Production | Staging | Local}
- User type: {Anonymous | Authenticated | Admin}
- First observed: {date}

### Steps to Reproduce
1. {Navigate to / perform action}
2. {Perform next action}
3. {Perform next action}
4. **Observe:** {incorrect behavior}

### Expected Behavior
{What should happen instead.}

### Actual Behavior
{What actually happens. Include error messages, console output, screenshots.}

### Impact
- Users affected: {percentage or count}
- Frequency: {every time | intermittent | specific conditions}
- Workaround: {exists / none}

---

### Claude Code Context

#### Suspected Root Cause
{Where the bug likely lives, if known.}
- File: `src/components/LoginForm.tsx:87`
- Issue: `isSubmitting` state set to `true` on validation error but never reset

#### Relevant Files
- `src/components/LoginForm.tsx` - Form component with the bug
- `tests/components/LoginForm.test.tsx` - Existing tests (gap here)
- `src/hooks/useAuth.ts` - Auth hook used by the form

#### Test Gap Analysis
- Existing tests cover: {what's currently tested}
- Missing test: {what test would have caught this bug}

#### Bug Fix Workflow (TDD)
1. Write a failing test that reproduces the bug
2. Verify the test fails (confirms the bug exists)
3. Fix the bug with minimum code change
4. Verify the test passes
5. Run full test suite to check for regressions

#### Verification
```bash
# Run the specific test
npm test -- --grep "LoginForm submit"

# Run related tests
npm test -- src/components/LoginForm.test.tsx

# Full regression check
npm test

约束

• 只修复 Bug——不要重构周边代码
• 不要更改组件的公共 API
• 确保所有现有测试继续通过

---

### 3. Tech Debt Ticket

```markdown
## [TECH-XXX] Refactor: {Area} - {Improvement}

**Type:** Tech Debt
**Priority:** {High | Medium | Low}
**Points:** {3 | 5 | 8}
**Labels:** {refactor, performance, maintainability, testing}

---

### Problem Statement
{What is wrong with the current implementation and why it matters.
Include concrete pain points: slow CI, frequent bugs, developer confusion.}

### Current State
- File: `{path}` ({N} lines)
- Test coverage: {X}%
- Cyclomatic complexity: {N}
- Related bugs: {PROJ-XXX, PROJ-YYY}
- Pain frequency: {how often this causes issues}

### Proposed Change
{What specifically should change and why this approach.}

### Acceptance Criteria
- [ ] {Specific structural change completed}
- [ ] All existing tests pass without modifying test assertions
- [ ] No public API changes (existing consumers unaffected)
- [ ] Test coverage >= {X}%
- [ ] {Measurable improvement metric}

### Risk Assessment
- Risk level: {Low | Medium | High}
- Mitigation: {run full regression, deploy behind flag, etc.}

### Business Justification
{Why this is worth doing now. E.g., "Reduces average bug fix time from 4h to 1h"
or "Enables upcoming feature PROJ-XXX which requires clean separation."}

---

### Claude Code Context

#### Relevant Files
- `{file}` - Current implementation to refactor
- `{test file}` - Existing tests (must not break)
- `{dependent file}` - Consumer of the API being refactored

#### Pattern Reference
Follow the pattern established in `{good example file}` for the new structure.

#### Constraints
- Do NOT change public APIs or exports
- Do NOT modify test assertions (tests should pass as-is)
- Do NOT introduce new dependencies
- Keep backwards compatibility

#### Verification
```bash
# Existing tests must pass unchanged
npm test

# No type errors
npm run typecheck

# Lint clean
npm run lint

# Coverage target
npm test -- --coverage

---

### 4. Epic Breakdown Ticket

```markdown
## [EPIC-XXX] {Epic Name}

**Type:** Epic
**Priority:** {Critical | High | Medium}
**Target:** {Sprint/milestone}

---

### Objective
{One paragraph: what this epic achieves and why it matters.}

### Success Metrics
- {Measurable outcome 1}
- {Measurable outcome 2}

### User Workflows
{The user journey this epic covers, broken into steps.}
1. {Step 1: Discovery/Entry}
2. {Step 2: Core Action}
3. {Step 3: Completion/Result}

### Ticket Breakdown

| # | Ticket | Type | Points | Dependencies |
|---|--------|------|--------|-------------|
| 1 | {title} | Feature | 3 | None |
| 2 | {title} | Feature | 5 | #1 |
| 3 | {title} | Feature | 3 | None |
| 4 | {title} | Feature | 2 | #2, #3 |
| 5 | {title} | Tech Debt | 3 | None |

### Slicing Strategy
{How the epic was broken down. Reference the technique used.}

### Agent Team Mapping
{If using agent teams, how features map to agents.}
- Feature Agent 1: Tickets #1, #2
- Feature Agent 2: Tickets #3, #4
- Parallel execution: #1 and #3 can run simultaneously
- Sequential: #2 depends on #1, #4 depends on #2 and #3

---

Epic 拆分技巧

将 Epic 拆分为工单时，使用以下策略之一：

技巧	适用场景	示例
按工作流步骤拆分	用户旅程明确	浏览 > 播放 > 保存 > 分享
按数据类型拆分	存在多种数据类型	文本帖子、图片、视频
按用户角色拆分	权限不同	匿名用户、已认证用户、管理员
按 CRUD 拆分	数据操作	创建、读取、更新、删除
优先覆盖正常流程	增量交付	先实现成功流程，再处理错误
按边界拆分	系统集成	分别处理前端、API、数据库

经验法则

• 每张工单：由一名开发者/Agent 完成，需 1-3 天
• 验收标准超过 5 条 = 拆分工单
• 故事点超过 8 点 = 必须拆分
• 每张工单都应能独立部署（即使需要通过功能标志控制）
• 工单排序：先处理最简单、基础性最强的工单

---

Claude Code Ready 检查清单

在工单准备好交由 AI Agent 执行之前，请确认：

┌─────────────────────────────────────────────────────────────────┐
│  CLAUDE CODE READY CHECKLIST                                     │
│  ──────────────────────────────────────────────────────────────  │
│                                                                  │
│  CONTEXT                                                         │
│  ☐ Relevant files listed with full paths                         │
│  ☐ Pattern reference points to a real file to follow             │
│  ☐ API contract defined (request/response shapes)                │
│  ☐ Database changes specified (tables, columns, migrations)      │
│  ☐ Environment variables listed (existing + new)                 │
│                                                                  │
│  SCOPE                                                           │
│  ☐ Out of Scope section explicitly states what NOT to do         │
│  ☐ Constraints section lists files/modules NOT to modify         │
│  ☐ Ticket covers one logical change (atomic)                     │
│  ☐ Estimable at ≤ 5 story points                                │
│                                                                  │
│  VERIFICATION                                                    │
│  ☐ Test command provided (exact command, not "run tests")        │
│  ☐ Lint command provided                                         │
│  ☐ Typecheck command provided                                    │
│  ☐ Acceptance criteria are Given-When-Then or checkboxed         │
│  ☐ Each criterion is independently pass/fail testable            │
│                                                                  │
│  QUALITY                                                         │
│  ☐ Title is imperative verb + object + context                   │
│  ☐ Title under 80 characters                                     │
│  ☐ Description explains WHY, not just WHAT                       │
│  ☐ 2-5 acceptance criteria (not more)                            │
│  ☐ No vague language ("fast", "good UX", "clean")               │
│                                                                  │
│  If any box is unchecked, the ticket is NOT ready.               │
└─────────────────────────────────────────────────────────────────┘

---

反模式（切勿采用）

1. 只有标题的工单

Title: Fix login
Description: (empty)

失败原因： 没有上下文、没有验收标准、没有文件引用。Claude Code 只能猜测，而且很可能猜错。

2. 长篇大论

Title: Implement new onboarding
Description: (3 pages mixing UI, backend, analytics, email, and future ideas)

失败原因： 规模不小，也不独立。Agent 团队无法并行处理。应拆分为 5 张以上工单。

3. 模糊的需求

Acceptance Criteria:
- Should be fast
- UX should be good
- Should work on mobile

失败原因： 无法衡量，也无法测试。应替换为：“响应时间 < 200ms”、“符合 WCAG 2.1 AA”、“视口宽度为 320px 时无水平滚动条。”

4. 过度规定解决方案

Title: Use Redis to cache user sessions
Description: Install Redis, configure connection pooling, set TTL to 3600...

失败原因： 规定了解决方案，而不是描述问题。应描述“会话查询耗时 500ms，需要低于 50ms”，让 Agent 自行选择方案。

5. 缺少文件信息的工单

Description: Update the auth module to support OAuth.

对 AI 来说为何会失败：“认证模块”可能涉及 20 个文件。Claude Code 需要明确路径：src/services/auth.ts、src/middleware/auth.ts、src/routes/auth.ts。

6. 缺少验证步骤的工单

Acceptance Criteria:
- OAuth login works
- Users can sign in with Google

**为何会失败：**没有测试命令，也没有验证步骤。当 Claude Code 能够验证自己的工作时，表现会显著提升。

---

好与坏的示例

不好的示例：含糊的功能工单

Title: Add rate limiting to the API
Description: We need rate limiting on our endpoints.

好的示例：适用于 Claude Code 的功能工单

Title: Add sliding window rate limiter to /api/generate endpoint

User Story:
As an API consumer, I want requests to be rate-limited
so that the service remains available under heavy load.

Acceptance Criteria:
AC1: Given an authenticated user making requests,
     when they exceed 10 requests per minute,
     then return 429 with Retry-After header.

AC2: Given a rate-limited user,
     when the window expires,
     then requests succeed again.

AC3: Given an unauthenticated request,
     when it hits /api/generate,
     then return 401 (rate limiting only applies to authed users).

Claude Code Context:
- Pattern: Follow `src/middleware/throttle.ts` for middleware structure
- File: Create `src/middleware/rateLimit.ts`
- Test: Create `tests/middleware/rateLimit.test.ts`
- Route: Modify `src/api/routes/generate.ts` to add middleware
- Constraint: Do NOT modify existing middleware or other endpoints

Verification:
  npm test -- --grep "rate-limit"
  npm run lint
  npm run typecheck

---

将工单映射到 Agent 团队

使用 agent-teams 工作流时，工单会直接映射到包含 10 个任务的流水线：

工单部分	映射到	Agent
标题 + 描述	任务 1：{name}-spec	功能 Agent
验收标准	任务 3：{name}-tests	功能 Agent（根据 AC 编写测试）
模式参考	任务 5：{name}-implement	功能 Agent（遵循模式）
验证部分	任务 6-7：verify + validate	质量 Agent + 功能 Agent
约束	全程执行	所有 Agent
Claude Code 上下文	启动时加载	功能 Agent 首先阅读

工单 → Agent 团队流程

1. Create ticket using templates above
2. Ticket becomes the feature spec in _project_specs/features/
3. Team Lead reads spec, creates 10-task dependency chain
4. Feature Agent uses ticket's Claude Code Context to start
5. Quality Agent uses ticket's Acceptance Criteria to verify
6. Review Agent reviews against ticket's Constraints
7. Security Agent scans based on ticket's scope
8. Merger Agent creates PR referencing the ticket ID

---

工单标题规范

类型	格式	示例
功能	Add {feature} for {user}	为听众添加剧集收藏功能
增强	Improve {what} in {where}	提升剧集动态中的搜索性能
Bug	Fix: {Component} - {Symptom}	修复：PlayerBar - 切换标签页时音频停止
技术债务	Refactor: {Area} - {Goal}	重构：AuthService - 提取令牌管理
安全	Security: {What} in {Where}	安全：为评论 API 添加输入清理
日常维护	Chore: {What}	日常维护：将 React 从 18 升级到 19

规则：

• 以祈使动词开头（Add、Fix、Improve、Refactor、Remove）
• 少于 80 个字符
• 包含受影响的组件/区域
• 描述要足够具体，以便与其他工单区分

---

面向 AI Agent 的故事点

AI Agent 的估算方式与人类不同。请使用以下校准标准：

点数	范围	Agent 用时	示例
1	单个文件，改动少于 20 行	~5 分钟	修正拼写错误、更新配置值
2	1-2 个文件，处理直接	~15 分钟	为表单添加字段、更新 API 响应
3	2-4 个文件，路径明确	~30 分钟	按照现有模式新增 API 端点
5	4-8 个文件，需要做一些决策	~1 小时	添加包含测试、模型和路由的新功能
8	8 个以上文件，较复杂	~2 小时	与外部服务集成、新增数据模型
13	范围过大，需要拆分	-	完整的认证系统、大规模重构

**规则：**如果超过 5 点，请考虑拆分。如果是 13 点，必须拆分。

---

与工单系统集成

Jira

• 使用自定义字段“Claude Code Context”填写 AI 专属部分
• 使用标签：claude-ready、needs-context、ai-blocked
• 使用“blocks/blocked by”关联工单，建立依赖链

Asana

• 使用自定义字段填写 Priority、Points、Type
• 使用子任务表示 10 个任务流水线的各个步骤
• 使用标签：claude-ready、needs-refinement

Linear

• 使用内置 Claude Code Context 部分的问题模板
• 使用标签标明工单类型和 Claude 就绪状态
• 使用项目将工单归入史诗

GitHub Issues

• 使用问题模板（.github/ISSUE_TEMPLATE/）
• 使用标签：feature、bug、tech-debt、claude-ready
• 使用里程碑管理史诗

---

命令：/create-ticket

当用户要求创建工单时，请遵循以下工作流：

步骤 1：收集上下文

询问用户：

1. 类型是什么？（功能 / Bug / 技术债务）
2. 简要描述需要完成的工作
3. 涉及代码库的哪一部分？

第 2 步：自动检测上下文

• 阅读相关文件，了解当前实现
• 从现有代码中找出应遵循的模式
• 查找现有测试，了解测试惯例
• 检查可能受影响的相关文件

第 3 步：生成工单

使用上方合适的模板，填写以下内容：

• 所有 Claude Code 上下文字段（自动检测）
• 验收标准（根据描述得出）
• 验证命令（来自项目的 CLAUDE.md 或 package.json）
• 约束（基于代码库分析）

第 4 步：使用清单验证

根据生成的工单执行 Claude Code 就绪清单。 标记所有未勾选项，供用户处理。

第 5 步：输出

按模板格式呈现工单，可直接粘贴到 Jira/Asana/Linear。

---

就绪定义（适用于 Sprint）

工单满足以下条件后即可纳入 Sprint：

• 通过 INVEST+C 标准
• Claude Code 就绪清单已完成
• 已识别依赖项且不存在阻碍
• 已分配故事点数
• 已附上设计稿/模型图（如适用）
• 团队已审核验收标准

完成定义

工单满足以下条件后即可视为完成：

• 已验证所有验收标准（通过/未通过）
• 已编写并通过测试
• 已完成代码审查（无严重/高危问题）
• 安全扫描已通过
• Lint 和类型检查均无问题
• 新代码覆盖率 >= 80%
• 已创建 PR，并附上完整的流水线结果
• 已更新文档（如适用）