ticket-craft

Ticket Craft Skill

AI エージェントが自律的に実行できるソフトウェアチケットを作成します。

目的： ソフトウェアエンジニアリングのベストプラクティス（INVEST、Given-When-Then、Definition of Ready）と、Claude Code 固有のコンテキスト要件を組み合わせたチケット形式を定義します。このスキルで作成されたすべてのチケットは「Claude Code Ready」です。つまり、エージェントが明確化の質問をせずに着手して実行できます。

対応： 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 - Independent（独立性）	別のチケットを待たずに完了できますか？	文書化されていない依存関係によりブロックされる
N - Negotiable（交渉可能性）	実装方法を調整する余地がありますか？	実装の詳細を過剰に規定している
V - Valuable（価値）	誰がどのような恩恵を受けるか説明できますか？	ユーザー価値やビジネス価値が明確でない
E - Estimable（見積もり可能性）	チームが規模を見積もるために十分理解していますか？	曖昧すぎる、または大きすぎて見積もれない
S - Small（小ささ）	1 人で 1〜3 日以内に完了できますか？	受け入れ基準が 5 項目を超えている
T - Testable（テスト可能性）	合否を判定するテストを書けますか？	「速い」「UX が良い」などの曖昧な表現を使っている
C - Claude-Ready	AI エージェントが明確化の質問をせずに実行できますか？	ファイル参照、パターン、検証方法、制約が不足している

---

チケットの種類

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

制約

• バグのみを修正し、周辺コードはリファクタリングしないでください
• コンポーネントの公開 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

---

エピックを分割するテクニック

エピックをチケットに分割する際は、次のいずれかの方法を使います。

テクニック	使用する場面	例
ワークフローのステップ別	ユーザーの行動経路が明確な場合	閲覧 > 再生 > 保存 > 共有
データの種類別	複数のデータタイプがある場合	テキスト投稿、画像、動画
ユーザーロール別	権限が異なる場合	匿名ユーザー、認証済みユーザー、管理者
CRUD 別	データ操作の場合	作成、読み取り、更新、削除
ハッピーパスを先に	段階的に提供する場合	まず成功フロー、次にエラー
境界別	システム連携の場合	フロントエンド、API、データベースを個別に分割

目安

• 各チケット：開発者またはエージェント 1 人あたり 1〜3 日の作業
• 受け入れ基準が 5 項目を超える場合は、チケットを分割します
• ストーリーポイントが 8 を超える場合は、必ず分割します
• すべてのチケットは、機能フラグを使用する場合も含め、単独でデプロイ可能にします
• チケットは、最も簡単で基盤となるものから順に並べます

---

Claude Code Ready チェックリスト

チケットを AI エージェントが実行できる状態にする前に、次の点を確認してください。

┌─────────────────────────────────────────────────────────────────┐
│  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)

うまくいかない理由： 小さくなく、独立していません。エージェントチームで並列化できません。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 にする必要がある」と記述し、エージェントに方法を選ばせてください。

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-teams ワークフローを使用する場合、チケットは10タスクのパイプラインに直接対応します。

チケットのセクション	対応先	エージェント
タイトルと説明	タスク1：{name}-spec	機能エージェント
受け入れ条件	タスク3：{name}-tests	機能エージェント（AC からテストを作成）
パターンの参照	タスク5：{name}-implement	機能エージェント（パターンに従う）
検証セクション	タスク6～7：verify + validate	品質エージェント + 機能エージェント
制約	全工程で適用	すべてのエージェント
Claude Code のコンテキスト	開始時に読み込み	機能エージェントが最初に読む

チケットからエージェントチームへのフロー

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}	エピソードフィードの検索パフォーマンスを改善
バグ	Fix: {Component} - {Symptom}	Fix: PlayerBar - タブ切り替え時に音声が停止する
技術的負債	Refactor: {Area} - {Goal}	Refactor: AuthService - トークン管理を切り出す
セキュリティ	Security: {What} in {Where}	Security: コメント API に入力のサニタイズを追加
雑務	Chore: {What}	Chore: React を 18 から 19 にアップグレード

ルール：

• 命令形の動詞（Add、Fix、Improve、Refactor、Remove）で始めます
• 80文字未満にします
• 影響を受けるコンポーネントまたは領域を含めます
• 他のチケットと区別できるほど具体的にします

---

AI エージェント向けストーリーポイント

AI エージェントの見積もりは、人間とは異なります。次の基準を使用してください。

ポイント	範囲	エージェントの所要時間	例
1	単一ファイル、変更行数20行未満	約5分	誤字の修正、設定値の更新
2	1～2ファイル、単純な作業	約15分	フォームへのフィールド追加、API レスポンスの更新
3	2～4ファイル、明確な手順	約30分	既存のパターンに沿った新しい API エンドポイント
5	4～8ファイル、いくつかの判断が必要	約1時間	テスト、モデル、ルートを含む新機能
8	8ファイル以上、複雑	約2時間	外部サービスとの連携、新しいデータモデル
13	大きすぎるため、分割が必要	-	認証システム全体、大規模なリファクタリング

**ルール：**5ポイントを超える場合は、分割を検討してください。13ポイントの場合は、必ず分割してください。

---

チケット管理システムとの連携

Jira

• AI 専用セクションには、カスタムフィールド「Claude Code Context」を使用します
• ラベルには claude-ready、needs-context、ai-blocked を使用します
• 依存関係をつなぐには、「blocks/blocked by」でチケットをリンクします

Asana

• 「Priority」「Points」「Type」にはカスタムフィールドを使用します
• 10タスクのパイプラインの手順にはサブタスクを使用します
• タグには claude-ready、needs-refinement を使用します

Linear

• Claude Code Context セクションを組み込んだ課題テンプレートを使用します
• チケットの種類と Claude Code 対応状況にはラベルを使用します
• チケットをエピックにまとめるにはプロジェクトを使用します

GitHub Issues

• 課題テンプレート（.github/ISSUE_TEMPLATE/）を使用します
• ラベルには feature、bug、tech-debt、claude-ready を使用します
• エピックにはマイルストーンを使用します

---

コマンド：/create-ticket

ユーザーからチケットの作成を依頼された場合は、次のワークフローに従います。

ステップ1：コンテキストを収集する

ユーザーに次のことを尋ねます。

1. 種類は何ですか？（機能／バグ／技術的負債）
2. 作業内容の簡単な説明
3. コードベースのどの部分が関係しますか？

ステップ 2: コンテキストの自動検出

• 関連するファイルを読み、現在の実装を理解します
• 既存のコードから従うべきパターンを特定します
• 既存のテストを見つけ、テストの慣習を理解します
• 影響を受ける可能性のある関連ファイルを確認します

ステップ 3: チケットの生成

上記の適切なテンプレートを使用し、以下を記入します:

• すべての Claude Code Context フィールド (自動検出)
• 受け入れ基準 (説明から導出)
• 検証コマンド (プロジェクトの CLAUDE.md または package.json から)
• 制約事項 (コードベースの分析に基づく)

ステップ 4: チェックリストによる検証

生成されたチケットに対して Claude Code Ready Checklist を実行します。 未チェックの項目があれば、ユーザーが対応すべきものとしてフラグを立てます。

ステップ 5: 出力

チケットをテンプレート形式で提示します。Jira/Asana/Linear にそのまま貼り付けられます。

---

準備完了の定義 (スプリント向け)

チケットは以下の条件を満たすとき、スプリントに投入できます:

• INVEST+C 基準を満たしている
• Claude Code Ready Checklist が完了している
• 依存関係が特定され、ブロックが解除されている
• ストーリーポイントが割り当てられている
• 設計/モックアップが添付されている (該当する場合)
• 受け入れ基準がチームによってレビューされている

完了の定義

チケットは以下の条件を満たすとき、完了です:

• すべての受け入れ基準が検証されている (合格/不合格)
• テストが作成され、合格している
• コードがレビューされている (Critical/High の問題がない)
• セキュリティスキャンに合格している
• Lint と型チェックがクリーンである
• 新しいコードのカバレッジが 80% 以上である
• 完全なパイプライン結果を含む PR が作成されている
• ドキュメントが更新されている (該当する場合)