jira:work について
コーディング作業向けの Jira ワークオーケストレーションスキルです。事前の質問、段階別実行、エージェントの並列化、キャッシュ、早期終了を備え、作業の複雑さに応じて FAST・STANDARD・FULL を選びます。Jira の状態更新、作業時間の記録、コミット、PR の関連付けも行います。
主な機能
- 01事前に確認事項を収集
- 02FAST・STANDARD・FULL の選択
- 03ワークフロー各段階の並列実行
- 04Jira と Confluence の検索結果をキャッシュ
- 05早期終了と復旧手順の適用
- 06Jira の状態・作業時間・関連付けを更新
活用シーン
- 01小規模なドキュメントや設定の変更
- 02複数ファイルにまたがるバグ修正や小規模機能
- 03アーキテクチャやセキュリティ作業の分析と実装の調整
- 04コミットを作成し、プルリクエストを Jira 課題に関連付け
インストール
コマンドをコピーしてターミナルで実行します。
$
npx skills add https:/インストール後、Claude Code で/jira:workを入力して読み込まれたか確認します。
詳細
Jira 作業オーケストレーション v5.1（最適化版）
インテリジェントな質問収集、段階的な実行、キャッシュ、最大限の並列化を実現する高性能なワークフローです。
v5.1 の主な機能：
- ❓ 質問優先プロトコル - 作業を始める前に、確認の質問をすべて行います
- ⚡ 3 つの実行ティア： FAST（3～4 エージェント） | STANDARD（6～8） | FULL（10～12）
- 🚀 40％高速化： 可能な箇所でフェーズを並列実行します
- 💾 キャッシュレイヤー： Jira／Confluence の検索結果をメモ化します
- 🎯 スマートゲート： 5 つのゲートを 3 つの並列ゲートグループに統合します
- 🔀 早期終了： 軽微な変更では不要なフェーズをスキップします
フェーズ 0：質問収集（必須）
作業を始める前に、Claude は質問をして十分なコンテキストを収集しなければなりません。
QUESTION-GATHERING PROTOCOL:
═════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────┐
│ STEP 1: Initial Analysis (~30 seconds) │
│ ───────────────────────────────────────── │
│ • Parse Jira issue description │
│ • Identify ambiguous requirements │
│ • Detect missing technical details │
│ • Check for undefined acceptance criteria │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ STEP 2: Generate Question Categories │
│ ──────────────────────────────────── │
│ │
│ 📋 REQUIREMENTS QUESTIONS │
│ • What is the expected behavior? │
│ • What are the acceptance criteria? │
│ • Are there edge cases to consider? │
│ • What should happen on errors? │
│ │
│ 🔧 TECHNICAL QUESTIONS │
│ • Which components/files are affected? │
│ • Are there existing patterns to follow? │
│ • What dependencies are involved? │
│ • Are there performance requirements? │
│ │
│ 🎨 DESIGN QUESTIONS │
│ • UI/UX requirements (if applicable)? │
│ • API contract expectations? │
│ • Database schema changes needed? │
│ │
│ ⚠️ RISK QUESTIONS │
│ • Rollback strategy if something goes wrong? │
│ • Testing requirements? │
│ • Security considerations? │
│ │
│ 🔗 DEPENDENCY QUESTIONS │
│ • Are there blocking issues? │
│ • External team dependencies? │
│ • Timeline constraints? │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ STEP 3: Present Questions & Wait for Answers │
│ ──────────────────────────────────────────── │
│ • Present grouped questions clearly │
│ • Wait for user responses │
│ • Ask follow-up questions if needed │
│ • Confirm understanding before proceeding │
└─────────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────────┐
│ STEP 4: Confirmation │
│ ──────────────────── │
│ "Based on your answers, here's my understanding: │
│ [Summary of requirements] │
│ │
│ Is this correct? Should I proceed with implementation?" │
└─────────────────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════════════════
ティア別の質問カテゴリ
| ティア | 最小質問数 | 確認する項目 |
|---|---|---|
| FAST | 1～2 | 確認のみ（「X を更新するだけでよろしいですか？」） |
| STANDARD | 3～5 | 要件、影響を受けるファイル、テスト方法 |
| FULL | 5～10 | 技術仕様全般、アーキテクチャ、セキュリティ、ロールバック |
インテリジェントな質問の生成
interface QuestionContext {
issueKey: string;
issueType: string;
description: string;
acceptanceCriteria: string[];
labels: string[];
components: string[];
}
function generateQuestions(context: QuestionContext): Question[] {
const questions: Question[] = [];
// Requirements gaps
if (!context.acceptanceCriteria?.length) {
questions.push({
category: 'requirements',
priority: 'high',
question: 'What are the acceptance criteria for this issue?'
});
}
// Technical ambiguity
if (context.description.includes('should') || context.description.includes('might')) {
questions.push({
category: 'technical',
priority: 'medium',
question: 'The description mentions "should/might" - is this optional or required behavior?'
});
}
// Error handling
if (context.issueType === 'Story' && !context.description.includes('error')) {
questions.push({
category: 'requirements',
priority: 'medium',
question: 'How should the system handle error cases?'
});
}
// Testing strategy
if (!context.labels.includes('tested') && !context.labels.includes('no-tests')) {
questions.push({
category: 'technical',
priority: 'low',
question: 'What level of test coverage is expected?'
});
}
// Security implications
if (detectSecurityKeywords(context.description)) {
questions.push({
category: 'security',
priority: 'high',
question: 'Are there specific security requirements or compliance needs?'
});
}
return questions;
}
// Example question output
const exampleQuestions = `
Before I start working on ${issueKey}, I have a few questions:
**Requirements:**
1. The description mentions "user authentication" - should this support both email/password and OAuth, or just one?
2. What should happen if a user's session expires mid-action?
**Technical:**
3. Should I follow the existing auth patterns in src/auth/, or is there a new approach you prefer?
4. Are there specific performance requirements (e.g., max auth latency)?
**Testing:**
5. Should I add integration tests with the OAuth provider, or mock those?
Please answer these questions and I'll proceed with implementation.
`;
スキップ条件（FAST ティアのみ）
以下のすべてに該当する場合、質問をスキップできます。
- 課題タイプが Bug、Sub-task、または Documentation である
- 説明が非常に具体的である（50 語未満）
- 受け入れ条件が明確に定義されている
- 変更対象のファイルが明示されている
- セキュリティへの影響が検出されない
function shouldSkipQuestions(context: QuestionContext): boolean {
const skipTypes = ['Bug', 'Sub-task', 'Documentation', 'Task'];
const hasSpecificDescription = context.description.split(' ').length < 50;
const hasClearAC = context.acceptanceCriteria.length >= 2;
const hasFilesMentioned = /\.(ts|js|py|go|java|rb)/.test(context.description);
const noSecurityImplications = !detectSecurityKeywords(context.description);
return (
skipTypes.includes(context.issueType) &&
hasSpecificDescription &&
hasClearAC &&
hasFilesMentioned &&
noSecurityImplications
);
}
クイックスタート
/jira:work <issue-key> [--tier=auto|fast|standard|full] [--skip-questions]
注： --skip-questions は FAST ティアおよび軽微な変更の場合のみ使用できます。
ティアの自動選択ロジック
FAST: docs-only | config | typo | readme | 1-2 files
STANDARD: bug-fix | minor-feature | refactor | 3-10 files
FULL: major-feature | architectural | security | 10+ files
最適化されたアーキテクチャ（v5.1）
┌─────────────────────────────────────────────────────────────────────────┐
│ JIRA WORK ORCHESTRATOR v5.1 - QUESTION-FIRST EXECUTION │
│ ⚡ Optimized for Speed ⚡ │
├─────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────────────────────────────────────┐ │
│ │ TIER SELECTOR (runs first, ~500ms) │ │
│ │ Analyze: issue type, labels, files, complexity → select tier │ │
│ └────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ┌─────────────────┼─────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ FAST │ │ STANDARD │ │ FULL │ │
│ │ 3-4 agnt │ │ 6-8 agnt │ │10-12 agnt│ │
│ │ ~2 min │ │ ~5 min │ │ ~10 min │ │
│ └──────────┘ └──────────┘ └──────────┘ │
│ │
│ ═══════════════════════════════════════════════════════════════════ │
│ │
│ PARALLEL EXECUTION LANES │
│ ┌──────────────────────────────────────────────────────────────────┐ │
│ │ LANE 1: CODE PATH │ LANE 2: CONTEXT (cached) │ │
│ │ ───────────────── │ ───────────────────── │ │
│ │ [EXPLORE]──▶[PLAN]──▶ │ [JIRA]──▶[CONFLUENCE] │ │
│ │ │ │ │ │ │ │ │
│ │ ▼ ▼ │ ▼ ▼ │ │
│ │ [CODE]──▶[TEST+QG] │ [CACHE] [CACHE] │ │
│ │ \ / │ │ │
│ │ ▼ ▼ │ │ │
│ │ [COMMIT] │ │ │
│ └──────────────────────────────────────────────────────────────────┘ │
│ │
│ ═══════════════════════════════════════════════════════════════════ │
│ │
│ GATE GROUPS (Parallel) │
│ ┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │
│ │ GROUP 1 │ │ GROUP 2 │ │ GROUP 3 │ │
│ │ LINT+FORMAT │ │ SECURITY+DEPS │ │ COVERAGE+CMPLX│ │
│ │ (haiku) │ │ (haiku) │ │ (sonnet) │ │
│ └───────────────┘ └───────────────┘ └───────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────┘
段階的な実行モード
FAST モード（3～4 エージェント、約 2 分）
用途： ドキュメント、設定、誤字、README、1～2 ファイルの変更
// Single consolidated agent for FAST mode
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `FAST MODE: Complete ${issueKey} end-to-end:
1. Quick context from Jira (cached if available)
2. Make the simple change
3. Run lint + format (auto-fix)
4. Commit and push
Skip: Full exploration, coverage check, complexity analysis
Output: { completed: true, files: [], commitSha: string }`
});
// Parallel: Basic quality check
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: "Lint check only: npx eslint --fix && npx prettier --write"
});
早期終了条件：
- コード変更なし（ドキュメントのみ）→ すべての品質ゲートをスキップします
- 設定のみの変更 → カバレッジと複雑度の確認をスキップします
- README／誤字 → コミット以外のすべてをスキップします
STANDARD モード（6～8 エージェント、約 5 分）
用途： バグ修正、小規模な機能、リファクタリング、3～10 ファイル
PARALLEL EXECUTION GRAPH:
═════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────┐
│ WAVE 1 (Parallel Launch - 3 agents) │
│ ┌───────────┐ ┌───────────┐ ┌───────────────────┐ │
│ │ EXPLORE │ │ JIRA │ │ CONFLUENCE CACHE │ │
│ │ (haiku) │ │ (cached) │ │ (cached) │ │
│ └─────┬─────┘ └─────┬─────┘ └─────────┬─────────┘ │
│ └──────────────┼──────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ WAVE 2: PLAN+CODE (1 consolidated agent) │ │
│ │ - Receive context from Wave 1 │ │
│ │ - Plan inline (no separate planning agent) │ │
│ │ - Execute code changes │ │
│ └─────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ WAVE 3: TEST + QUALITY (3 parallel gate groups) │ │
│ │ ┌─────────┐ ┌─────────────┐ ┌─────────────────┐ │ │
│ │ │LINT+FMT │ │SECURITY+DEPS│ │COVERAGE+COMPLEX │ │ │
│ │ │ (haiku) │ │ (haiku) │ │ (sonnet) │ │ │
│ │ └─────────┘ └─────────────┘ └─────────────────┘ │ │
│ └─────────────────────────────────────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ WAVE 4: COMMIT (1 agent, includes PR) │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════
// WAVE 1: Parallel context gathering (with cache)
const [exploreResult, jiraContext, confluenceContext] = await Promise.all([
Task({
subagent_type: "Explore",
model: "haiku",
prompt: `Quick codebase analysis for ${issueKey}:
- Identify affected files (Glob/Grep)
- Find test files
- Map immediate dependencies`
}),
getCached('jira', issueKey) || Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `Fetch and cache Jira issue ${issueKey}`
}),
getCached('confluence', issueKey) || Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: "Search Confluence for related docs (cache result)"
})
]);
// WAVE 2: Consolidated Plan+Code (single agent, inline planning)
const codeResult = await Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `Implement ${issueKey} with inline planning:
Context: ${JSON.stringify({ exploreResult, jiraContext })}
1. [INLINE PLAN] Quick design decisions (no separate agent)
2. [CODE] Implement changes following plan
3. Output: { files: [], plan: string, summary: string }`
});
// WAVE 3: 3 Gate Groups in Parallel (consolidates 5 gates)
const [lintGate, securityGate, coverageGate] = await Promise.all([
// Group 1: Lint + Format (combines Static Analysis)
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `GATE GROUP 1 - LINT+FORMAT:
- ESLint with --fix
- Prettier with --write
Output: { passed: boolean, issues: [], autoFixed: number }`
}),
// Group 2: Security + Dependencies (combines 2 gates)
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `GATE GROUP 2 - SECURITY+DEPS:
- gitleaks (secrets)
- npm audit (vulnerabilities)
- Check for outdated critical deps
Output: { passed: boolean, vulns: [], outdated: [] }`
}),
// Group 3: Coverage + Complexity (requires more analysis)
Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `GATE GROUP 3 - COVERAGE+COMPLEXITY:
- Run tests with coverage (threshold: 80%)
- Check cyclomatic complexity (max: 10)
- Identify complex functions
Output: { passed: boolean, coverage: number, complexity: [] }`
})
]);
// WAVE 4: Commit + PR (single agent)
await Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `Complete ${issueKey}:
Quality: ${JSON.stringify({ lintGate, securityGate, coverageGate })}
1. Commit with smart message
2. Push to feature branch
3. Create PR with quality report
4. Link to Jira
Output: { commitSha, prUrl, jiraLinked }`
});
FULL モード（10～12 エージェント、約 10 分）
用途： 大規模な機能、アーキテクチャの変更、セキュリティ上重要な変更
FULL MODE EXECUTION:
═════════════════════════════════════════════════════════════
WAVE 1: Deep Analysis (4 parallel agents)
├── EXPLORE: Deep codebase analysis
├── JIRA: Full issue context + linked issues
├── CONFLUENCE: Architecture docs, ADRs
└── SECURITY-PRE: Pre-implementation security review
WAVE 2: Architecture Planning (2 agents)
├── PLAN: Detailed implementation plan with DAG
└── TEST-PLAN: Test strategy and scenarios
WAVE 3: Implementation (2-4 agents based on subtasks)
└── CODE: Parallel subtask execution
WAVE 4: Comprehensive Quality (3 gate groups + deep security)
├── LINT+FORMAT
├── SECURITY+DEPS (with SAST)
├── COVERAGE+COMPLEXITY
└── DEEP-SECURITY: Full vulnerability analysis
WAVE 5: Finalization (2 agents)
├── COMMIT: Smart commit + PR
└── DOCUMENT: Confluence tech doc generation
═════════════════════════════════════════════════════════════
キャッシュレイヤー（v5.0 の新機能）
interface WorkflowCache {
jira: Map<string, JiraIssue>; // TTL: 5 minutes
confluence: Map<string, Page[]>; // TTL: 10 minutes
fileAnalysis: Map<string, Analysis>; // TTL: until file modified
gateResults: Map<string, GateResult>; // TTL: until code changed
}
// Cache-aware fetch pattern
async function getCached<T>(type: keyof WorkflowCache, key: string): Promise<T | null> {
const cache = workflowCache[type];
const entry = cache.get(key);
if (entry && !isExpired(entry)) {
return entry.value;
}
return null; // Cache miss - will fetch fresh
}
// Pre-warm cache at session start
async function prewarmCache(issueKey: string): Promise<void> {
// Parallel cache warming (runs during tier selection)
await Promise.all([
fetchAndCache('jira', issueKey),
fetchAndCache('confluence', getProjectKey(issueKey))
]);
}
キャッシュのメリット：
- 同じ課題を再実行：50％高速化（Jira／Confluence をキャッシュ）
- 同じセッションで複数の課題を処理：30％高速化（プロジェクトのコンテキストを共有）
- ファイルに変更なし：重複する分析をスキップ
早期終了の最適化
// Tier determines which gates can be skipped
const earlyExitRules = {
FAST: {
skip: ['coverage', 'complexity', 'deepSecurity', 'confluence-doc'],
require: ['lint']
},
STANDARD: {
skip: ['deepSecurity', 'confluence-doc'],
require: ['lint', 'security', 'coverage']
},
FULL: {
skip: [],
require: ['all']
}
};
// File-type based skips
const fileTypeSkips = {
'docs': ['coverage', 'complexity'], // .md, .txt, .rst
'config': ['coverage'], // .json, .yaml, .toml
'test': ['complexity'] // *.test.*, *.spec.*
};
// Apply early exit logic
function shouldSkipGate(gate: string, tier: Tier, files: string[]): boolean {
// Check tier rules
if (earlyExitRules[tier].skip.includes(gate)) return true;
// Check file-type rules
const fileTypes = detectFileTypes(files);
if (fileTypes.every(ft => fileTypeSkips[ft]?.includes(gate))) return true;
return false;
}
失敗からの復旧とコンテキストの最適化（v5.0）
目的： エージェントが回答の検索に手間取ったり、検索に失敗したりした場合に、コンテキストを無駄に消費するのを防ぎます。
検索タイムアウトの上限
const SEARCH_LIMITS = {
// Maximum attempts before giving up
maxSearchAttempts: 3,
// Time limits per search type
timeouts: {
glob: 5000, // 5 seconds
grep: 10000, // 10 seconds
explore: 30000, // 30 seconds
jiraFetch: 10000, // 10 seconds
confluence: 15000 // 15 seconds
},
// Context budget per phase (tokens)
contextBudget: {
EXPLORE: 5000,
PLAN: 3000,
CODE: 15000,
TEST: 5000,
QUALITY: 3000,
FIX: 8000,
COMMIT: 2000
}
};
ネガティブキャッシュ（失敗した検索のメモ化）
interface NegativeCache {
failedSearches: Map<string, {
query: string;
timestamp: number;
reason: string;
ttl: number; // Don't retry for this duration
}>;
}
// Prevent repeating failed searches
async function searchWithNegativeCache(query: string, searchFn: () => Promise<any>): Promise<any> {
const cacheKey = hashQuery(query);
const cached = negativeCache.get(cacheKey);
if (cached && !isExpired(cached)) {
// Return early with fallback instead of re-trying
return {
found: false,
reason: cached.reason,
suggestion: 'Try alternative search pattern'
};
}
try {
const result = await withTimeout(searchFn(), SEARCH_LIMITS.timeouts.grep);
return result;
} catch (error) {
// Cache the failure to prevent retry storms
negativeCache.set(cacheKey, {
query,
timestamp: Date.now(),
reason: error.message,
ttl: 5 * 60 * 1000 // Don't retry for 5 minutes
});
throw error;
}
}
コンテキストのチェックポイント
interface PhaseCheckpoint {
phase: string;
issueKey: string;
timestamp: string;
artifacts: {
filesIdentified: string[];
planSummary?: string;
codeChanges?: string[];
testResults?: any;
qualityScore?: number;
};
contextUsed: number; // Tokens consumed
canResume: boolean;
}
// Checkpoint after each phase to prevent re-work
async function checkpointPhase(phase: string, result: any): Promise<void> {
const checkpoint: PhaseCheckpoint = {
phase,
issueKey: currentIssue,
timestamp: new Date().toISOString(),
artifacts: extractArtifacts(result),
contextUsed: estimateTokens(result),
canResume: true
};
// Save to session storage (survives agent restarts)
await sessionStorage.set(`checkpoint:${currentIssue}:${phase}`, checkpoint);
}
// Resume from last checkpoint if context was lost
async function resumeFromCheckpoint(issueKey: string): Promise<PhaseCheckpoint | null> {
const phases = ['COMMIT', 'FIX', 'QUALITY', 'TEST', 'CODE', 'PLAN', 'EXPLORE'];
for (const phase of phases) {
const checkpoint = await sessionStorage.get(`checkpoint:${issueKey}:${phase}`);
if (checkpoint?.canResume) {
return checkpoint; // Resume from most recent valid checkpoint
}
}
return null;
}
エスカレーションのパターン
STRUGGLE DETECTION & ESCALATION:
═════════════════════════════════════════════════════════════════════════
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 1: Agent Self-Recovery (automatic) │
│ ───────────────────────────────────────── │
│ • 3 search attempts with query refinement │
│ • Broaden search pattern on failure │
│ • Try alternative file patterns │
│ • Timeout: 30 seconds total │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if still failing)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 2: Strategy Pivot (automatic) │
│ ───────────────────────────────── │
│ • Switch from Grep to Glob (or vice versa) │
│ • Use Task(Explore) agent for deeper search │
│ • Check registry for known patterns │
│ • Consult project structure cache │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if still failing)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 3: Graceful Degradation (automatic) │
│ ───────────────────────────────────────── │
│ • Proceed with partial context │
│ • Log what's missing for manual review │
│ • Mark result as "low confidence" │
│ • Add TODO comments for missing context │
└───────────────────────────┬─────────────────────────────────────────┘
│ (if critical blocker)
▼
┌─────────────────────────────────────────────────────────────────────┐
│ LEVEL 4: Human Escalation (requires intervention) │
│ ─────────────────────────────────────────────── │
│ • Pause workflow with clear status │
│ • Present what was tried and what failed │
│ • Request specific information needed │
│ • Checkpoint state for resume after input │
└─────────────────────────────────────────────────────────────────────┘
═════════════════════════════════════════════════════════════════════════
再試行の上限とサーキットブレーカー
interface RetryBudget {
maxRetries: number;
currentRetries: number;
backoffMs: number[];
circuitOpen: boolean;
lastFailure?: Date;
}
const retryBudgets: Record<string, RetryBudget> = {
jiraApi: { maxRetries: 3, currentRetries: 0, backoffMs: [1000, 2000, 4000], circuitOpen: false },
confluence: { maxRetries: 2, currentRetries: 0, backoffMs: [2000, 5000], circuitOpen: false },
githubApi: { maxRetries: 3, currentRetries: 0, backoffMs: [1000, 2000, 4000], circuitOpen: false },
codeSearch: { maxRetries: 3, currentRetries: 0, backoffMs: [500, 1000, 2000], circuitOpen: false }
};
// Circuit breaker pattern
async function withCircuitBreaker<T>(
service: string,
operation: () => Promise<T>
): Promise<T | null> {
const budget = retryBudgets[service];
// Check if circuit is open (too many recent failures)
if (budget.circuitOpen) {
const timeSinceFailure = Date.now() - (budget.lastFailure?.getTime() || 0);
if (timeSinceFailure < 60000) { // 1 minute cooldown
return null; // Skip this service, use fallback
}
budget.circuitOpen = false; // Reset circuit
}
for (let attempt = 0; attempt < budget.maxRetries; attempt++) {
try {
const result = await operation();
budget.currentRetries = 0; // Reset on success
return result;
} catch (error) {
budget.currentRetries++;
budget.lastFailure = new Date();
if (attempt < budget.maxRetries - 1) {
await sleep(budget.backoffMs[attempt]);
}
}
}
// Open circuit after exhausting retries
budget.circuitOpen = true;
return null;
}
フォールバック戦略
const FALLBACK_STRATEGIES = {
// When Jira API fails
jiraUnavailable: {
action: 'useLocalContext',
steps: [
'Parse issue key from branch name',
'Extract context from commit messages',
'Use cached issue data if available',
'Proceed with minimal context, mark as draft'
]
},
// When Confluence search fails
confluenceUnavailable: {
action: 'skipDocumentation',
steps: [
'Skip Confluence search in EXPLORE',
'Skip doc generation in COMMIT',
'Add TODO for manual documentation',
'Continue with code-only workflow'
]
},
// When codebase search fails
searchFailed: {
action: 'broaden',
steps: [
'Try parent directory',
'Use simpler glob pattern (*.ts instead of **/*.service.ts)',
'Search by keyword instead of path',
'Fall back to git log for file history'
]
},
// When quality gates timeout
gateTimeout: {
action: 'partialCheck',
steps: [
'Run only fast gates (lint, format)',
'Skip slow gates (coverage, complexity)',
'Mark PR as "needs-full-review"',
'Schedule async quality check'
]
}
};
// Apply fallback when primary strategy fails
async function withFallback<T>(
primary: () => Promise<T>,
fallbackKey: keyof typeof FALLBACK_STRATEGIES,
fallbackFn: () => Promise<T>
): Promise<{ result: T; usedFallback: boolean }> {
try {
const result = await withTimeout(primary(), 30000);
return { result, usedFallback: false };
} catch (error) {
console.log(`Primary failed, using fallback: ${fallbackKey}`);
const result = await fallbackFn();
return { result, usedFallback: true };
}
}
コンテキスト予算の適用
// Track context usage per phase
class ContextBudgetTracker {
private usage: Map<string, number> = new Map();
private readonly totalBudget = 100000; // tokens
consume(phase: string, tokens: number): boolean {
const current = this.usage.get(phase) || 0;
const phaseBudget = SEARCH_LIMITS.contextBudget[phase];
if (current + tokens > phaseBudget) {
console.warn(`Phase ${phase} exceeding budget: ${current + tokens}/${phaseBudget}`);
return false; // Deny consumption
}
this.usage.set(phase, current + tokens);
return true;
}
getRemaining(): number {
const used = Array.from(this.usage.values()).reduce((a, b) => a + b, 0);
return this.totalBudget - used;
}
shouldCheckpoint(): boolean {
return this.getRemaining() < 25000; // 25% remaining
}
shouldCompress(): boolean {
return this.getRemaining() < 10000; // 10% remaining
}
}
// Enforce budget during agent execution
const budgetTracker = new ContextBudgetTracker();
async function executeWithBudget(phase: string, operation: () => Promise<any>): Promise<any> {
if (budgetTracker.shouldCheckpoint()) {
await checkpointPhase(phase, { partial: true });
}
if (budgetTracker.shouldCompress()) {
await compressContext(); // Summarize and discard old messages
}
const result = await operation();
budgetTracker.consume(phase, estimateTokens(result));
return result;
}
まとめ：対策のクイックリファレンス
| 問題 | 検出方法 | 対策 |
|---|---|---|
| 検索に時間がかかりすぎる | 30 秒後にタイムアウト | パターンを広げ、別の方法を試す |
| 同じ検索が繰り返し失敗する | ネガティブキャッシュにヒット | フォールバックを使ってスキップし、再試行しない |
| コンテキストが不足する | 予算トラッカー | チェックポイントを作成して圧縮 |
| API が継続的に失敗する | サーキットブレーカーが開く | キャッシュデータを使うか、スキップ |
| エージェントがループから抜け出せない | 再試行回数が 3 回を超える | 人間にエスカレーション |
| フェーズが未完了 | 成果物が不足 | チェックポイントから再開 |
| 信頼度の低い結果 | フォールバックを使用 | レビュー対象としてマークし、TODO を追加 |
サブエージェント通信プロトコル
メッセージ形式
interface AgentMessage {
id: string;
from: string; // Agent identifier
to: string; // Target agent or "orchestrator"
phase: string; // Current workflow phase
type: "result" | "request" | "error" | "status";
payload: any;
timestamp: string;
}
結果の引き継ぎパターン
// Phase N agent completes and reports
const phaseResult = {
phase: "CODE",
status: "complete",
artifacts: {
filesModified: ["src/api/handler.ts", "src/utils/parser.ts"],
linesAdded: 245,
linesRemoved: 12
},
nextPhaseInput: {
filesToTest: ["src/api/handler.ts"],
coverageTargets: ["handler", "parser"]
}
};
// Orchestrator receives and forwards to Phase N+1
orchestrator.handoff("TEST", phaseResult.nextPhaseInput);
エラーのエスカレーション
// Agent encounters blocking error
if (error.severity === "critical") {
return {
type: "error",
escalate: true,
message: "Security vulnerability detected - blocking commit",
requiresHumanReview: true
};
}
エージェントレジストリ（v5.0 最適化版）
FAST モード（3-4 エージェント）
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | fast-implementer | haiku | エンドツーエンド：fetch→code→commit |
| 1 | lint-gate | haiku | 簡易 lint と format（並列） |
| 2* | fix-agent | sonnet | lint が失敗した場合のみ |
STANDARD モード（6-8 エージェント）
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | explore-agent | haiku | コードベースの分析 |
| 1 | jira-fetch | haiku | Issue のコンテキスト（キャッシュ済み） |
| 1 | confluence-fetch | haiku | ドキュメント検索（キャッシュ済み） |
| 2 | plan-code-agent | sonnet | 統合された計画と実装 |
| 3 | lint-format-gate | haiku | ゲートグループ 1 |
| 3 | security-deps-gate | haiku | ゲートグループ 2 |
| 3 | coverage-complex-gate | sonnet | ゲートグループ 3 |
| 4 | commit-pr-agent | sonnet | コミット + PR + Jira リンク |
FULL モード（10-12 エージェント）
| Wave | Agent | Model | Purpose |
|---|---|---|---|
| 1 | deep-explore | sonnet | コードベースの包括的な分析 |
| 1 | jira-full | haiku | Issue とリンクされた Issue |
| 1 | confluence-arch | sonnet | アーキテクチャドキュメント、ADR |
| 1 | security-pre | sonnet | 実装前のセキュリティレビュー |
| 2 | architect-planner | opus | 詳細な実装計画 |
| 2 | test-strategist | sonnet | テスト計画とシナリオ |
| 3 | code-agent (x2-4) | sonnet | サブタスクの並列実装 |
| 4 | gate-group-1 | haiku | Lint + Format |
| 4 | gate-group-2 | haiku | セキュリティ + 依存関係 |
| 4 | gate-group-3 | sonnet | カバレッジ + 複雑度 |
| 4 | deep-security | sonnet | SAST の完全な分析 |
| 5 | commit-pr-agent | sonnet | スマートコミット + 包括的な PR |
| 5 | confluence-doc | sonnet | 技術ドキュメントの生成 |
パフォーマンスの比較
┌────────────────────────────────────────────────────────────────┐
│ v4.2 vs v5.0 PERFORMANCE COMPARISON │
├────────────────────────────────────────────────────────────────┤
│ │
│ AGENT COUNT REDUCTION │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ v4.2: 13-18 agents (all tasks) │ │
│ │ v5.0: 3-4 (FAST) | 6-8 (STANDARD) | 10-12 (FULL) │ │
│ │ │ │
│ │ Average reduction: 40% fewer agents │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ EXECUTION TIME │
│ ┌────────────────────────────────────────────────────────┐ │
│ │ v4.2 │ v5.0 │ │
│ ├───────────────────────┼────────────────────────────────┤ │
│ │ Simple bug: ~8 min │ FAST: ~2 min (-75%) │ │
│ │ Feature: ~12 min │ STANDARD: ~5 min (-58%) │ │
│ │ Major: ~15 min │ FULL: ~10 min (-33%) │ │
│ └────────────────────────────────────────────────────────┘ │
│ │
│ GATE CONSOLIDATION │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ v4.2: 5 separate gates (5 agents) │ │
│ │ v5.0: 3 gate groups (3 agents, parallel) │ │
│ │ │ │
│ │ Group 1: Static Analysis + Formatting │ │
│ │ Group 2: Security Scanner + Dependency Health │ │
│ │ Group 3: Test Coverage + Complexity Analyzer │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ CACHING BENEFITS │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Same issue re-run: 50% faster │ │
│ │ Same session/project: 30% faster │ │
│ │ Unchanged files: Skip redundant analysis │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ COST REDUCTION (API calls) │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ FAST mode: ~70% fewer API calls │ │
│ │ STANDARD mode: ~45% fewer API calls │ │
│ │ haiku preference: Lower cost per agent │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└────────────────────────────────────────────────────────────────┘
実行あたりのエージェント総数（v5.0）：
- FAST：3-4 エージェント
- STANDARD：6-8 エージェント
- FULL：10-12 エージェント
v4.2 との比較： すべてのタスクタイプで 13-18 エージェントでした
Jira との連携
このコマンドは自動的に以下を行います：
- Issue を「In Progress」に遷移
- 進捗コメントを追加
- 作業時間を記録
- スマートコミットを作成
- PR を Issue にリンク
Confluence との連携（高度）
このワークフローは、ドキュメント作成のために Confluence と連携します：
自動生成されるドキュメント
// After successful commit, generate Confluence page
Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `Create Confluence documentation for ${issueKey}:
1. Generate technical design document
2. Document API changes (if any)
3. Create/update runbook entries
4. Add architecture diagrams (mermaid)
Use mcp__MCP_DOCKER__confluence_create_page`
});
使用する Confluence の機能
| 機能 | 目的 | トリガー |
|---|---|---|
| ページ作成 | 技術ドキュメントを自動作成 | COMMIT フェーズの後 |
| ページ更新 | 既存のドキュメントを更新 | ページが存在する場合 |
| 検索 | EXPLORE で関連ドキュメントを検索 | mcp__MCP_DOCKER__confluence_search |
| 添付ファイル | 品質レポート、図 | QUALITY フェーズの後 |
| ラベル | ドキュメントを分類 | 自動タグ付け |
| マクロ挿入 | Jira Issue の埋め込み、コードブロック | 技術ドキュメント |
ドキュメントテンプレート
// Technical Design Document Template
const techDocTemplate = {
title: `[${issueKey}] Technical Design - ${summary}`,
space: projectSpace,
labels: ["tech-doc", "auto-generated", projectKey],
sections: [
"Overview", "Problem Statement", "Solution Architecture",
"API Changes", "Database Changes", "Testing Strategy",
"Quality Metrics", "Deployment Notes"
]
};
EXPLORE フェーズでの Confluence 検索
// Search for related documentation
Task({
subagent_type: "Explore",
model: "haiku",
prompt: `Search Confluence for context:
Use mcp__MCP_DOCKER__confluence_search with query "${issueKey} OR ${component}"
1. Find related architecture docs
2. Locate existing runbooks
3. Check for similar implementations
4. Gather ADRs (Architecture Decision Records)`
});
GitHub との連携（高度）
このワークフローは GitHub と深く連携します：
ブランチ戦略
// Create feature branch with Jira issue key
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `Create feature branch:
git checkout -b feature/${issueKey.toLowerCase()}-${slugify(summary)}
git push -u origin feature/${issueKey}-description`
});
プルリクエストの機能
// Create PR with full quality integration
Task({
subagent_type: "general-purpose",
model: "sonnet",
prompt: `Create comprehensive PR for ${issueKey}:
1. Create PR: gh pr create --title "${issueKey}: ${summary}"
2. Add quality report to description
3. Add labels: gh pr edit --add-label "quality-passed"
4. Request reviewers: gh pr edit --add-reviewer "@team/code-owners"
5. Link to Jira in description
6. Post status check via gh api`
});
使用する GitHub の機能
| 機能 | 目的 | コマンド |
|---|---|---|
| ブランチ作成 | フィーチャーブランチ | git checkout -b |
| PR 作成 | 品質レポート付き | gh pr create |
| ステータスチェック | 品質ゲートのステータス | gh api /statuses |
| ラベル | PR を分類 | gh pr edit --add-label |
| レビュアー | 自動割り当て | gh pr edit --add-reviewer |
| プロジェクト | ボードで追跡 | gh project item-add |
| Actions | ワークフローを実行 | gh workflow run |
| リリース | リリースノートを自動生成 | gh release create |
GitHub Actions との連携
// Trigger quality workflow on PR
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `Trigger GitHub Actions workflow:
gh workflow run quality-gates.yml \\
--ref feature/${issueKey} \\
-f issue_key=${issueKey}`
});
品質レポート付きの PR 説明
## Summary
${summary}
**Jira Issue:** [${issueKey}](https://jira.company.com/browse/${issueKey})
## Quality Report
| Gate | Score | Status |
|------|-------|--------|
| Static Analysis | ${staticScore} | ${staticStatus} |
| Test Coverage | ${coverage}% | ${coverageStatus} |
| Security | ${securityScore} | ${securityStatus} |
| Complexity | ${complexityScore} | ${complexityStatus} |
| Dependencies | ${depsScore} | ${depsStatus} |
**Overall:** ${qualityScore}/100 (Grade: ${grade})
## Confluence Docs
- [Technical Design](${confluenceLink})
GitHub コミットステータス API
// Post quality results as commit status
Task({
subagent_type: "general-purpose",
model: "haiku",
prompt: `Update GitHub commit status:
gh api --method POST /repos/{owner}/{repo}/statuses/{sha} \\
-f state="${allPassed ? 'success' : 'failure'}" \\
-f description="Quality Score: ${qualityScore}/100" \\
-f context="quality-gates/curator"`
});
ワークフロー全体の連携図
┌─────────────────────────────────────────────────────────────────────────────┐
│ JIRA WORK ORCHESTRATOR v4.2.0 │
│ Integrated with Confluence, GitHub, and Curator │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────────┐ │
│ │ JIRA │◀──────────────────────────────────────────────────────────┐ │
│ │ Arbiter │ │ │
│ └─────┬─────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ PHASE 1: EXPLORE │ │ │
│ │ ┌──────────┐ ┌──────────────┐ ┌──────────────┐ │ │ │
│ │ │ Jira API │ │ Confluence │ │ Codebase │ │ │ │
│ │ │ Fetch │ │ Search │ │ Analysis │ │ │ │
│ │ └──────────┘ └──────────────┘ └──────────────┘ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ PHASE 2-4: PLAN → CODE → TEST │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ PHASE 5: QUALITY GATES (Curator) │ │ │
│ │ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │ │ │
│ │ │ Static │ │Coverage│ │Security│ │Complex │ │ Deps │ │ │ │
│ │ └────────┘ └────────┘ └────────┘ └────────┘ └────────┘ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ PHASE 6-7: FIX → COMMIT │ │ │
│ │ ┌──────────────┐ ┌───────────────────────────────────────┐ │ │ │
│ │ │ Auto-Fix │ │ GitHub Integration │ │ │ │
│ │ │ Agent │───▶│ Branch → Commit → PR → Status Check │ │ │ │
│ │ └──────────────┘ └───────────────────────────────────────┘ │ │ │
│ └───────────────────────────────────────────────────────────────────┘ │ │
│ │ │ │
│ ▼ │ │
│ ┌───────────────────────────────────────────────────────────────────┐ │ │
│ │ POST-COMMIT: Documentation │───┘ │
│ │ ┌──────────────────┐ ┌──────────────────┐ │ │
│ │ │ Confluence │ │ Jira │ │ │
│ │ │ - Tech Docs │ │ - Comment │ │ │
│ │ │ - Runbooks │ │ - Link PR │ │ │
│ │ └──────────────────┘ └──────────────────┘ │ │
│ └───────────────────────────────────────────────────────────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────────────┘
関連コマンド
Jira コマンド
/jira:status- 現在の作業セッションのステータスを確認/jira:sync- 変更を Jira と同期/jira:pr- プルリクエストを作成/jira:commit- スマートコミットを作成
Confluence コマンド
/confluence-publish- 技術ドキュメントを Confluence に公開します/atlassian-sync- Jira/Confluence と同期します
GitHub コマンド
- gh cli を使って品質レポート付きの PR を作成します
- gh api を使ってコミットのステータスを更新します
- gh workflow run を使ってワークフローを実行します
品質ゲートコマンド（Curator 提供）
/quality-check- 5 つの品質ゲートをすべて実行します/quality-fix- 可能な場合に問題を自動修正します/coverage-check- テストカバレッジを確認します（最小 80%）/security-scan- セキュリティ脆弱性スキャンを実行します/complexity-audit- コードの複雑さを確認します/dependency-audit- 依存関係の健全性を確認します
品質ゲートのしきい値
| ゲート | 指標 | しきい値 |
|---|---|---|
| 静的解析 | エラー | 0 |
| テストカバレッジ | 行カバレッジ | ≥ 80% |
| セキュリティスキャナー | 重大/高 CVE | 0 |
| 複雑度 | 循環的複雑度 | ≤ 10 |
| 複雑度 | 認知的複雑度 | ≤ 15 |
| 依存関係 | 重大な脆弱性 | 0 |
コメント
Markdown 対応