jira-safe

Jira SAFe（规模化敏捷框架）技能

在 Jira Cloud 中实现 SAFe 方法，用于管理 Epic、Feature、Story 和 Task。

适用场景

• 创建包含业务成果和验收标准的 Epic
• 按 SAFe 格式编写用户故事（“作为……，我想要……，以便……”）
• 将 Feature 拆分为包含验收标准的 Story
• 在 Story 下创建子任务
• 按正确的层级关联工作项（Epic → Feature → Story → Subtask）

重要：Next-Gen 与 Classic 项目

SCRUM 项目属于 Next-Gen（团队管理型）。主要区别如下：

方面	Classic（公司管理型）	Next-Gen（团队管理型）
Epic Link	customfield_10014	parent: { key: 'EPIC-KEY' }
Epic Name	customfield_10011	不可用
Subtask Type	'Sub-task'	'Subtask'
项目样式	classic	next-gen, simplified: true

务必先检测项目类型：

const projectInfo = await fetch(`${JIRA_URL}/rest/api/3/project/${PROJECT_KEY}`, { headers });
const project = await projectInfo.json();
const isNextGen = project.style === 'next-gen' || project.simplified === true;

Jira 中的 SAFe 层级

Portfolio Level:
└── Epic (Strategic Initiative)
    └── Feature (Benefit Hypothesis)
        └── Story (User Value)
            └── Subtask (Technical Work)

SAFe 模板

Epic 模板（Next-Gen）

// NOTE: Next-Gen projects do NOT use customfield_10011 (Epic Name)
const epic = {
  fields: {
    project: { key: 'PROJECT_KEY' },
    issuetype: { name: 'Epic' },
    summary: '[Epic ID]: [Epic Name] - [Business Outcome]',
    description: {
      type: 'doc',
      version: 1,
      content: [
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'Business Outcome' }]
        },
        {
          type: 'paragraph',
          content: [{ type: 'text', text: 'Describe the measurable business value...' }]
        },
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'Success Metrics' }]
        },
        {
          type: 'bulletList',
          content: [
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'Metric 1: [measurable target]' }] }]
            }
          ]
        },
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'Scope' }]
        },
        {
          type: 'paragraph',
          content: [{ type: 'text', text: 'What is in scope and out of scope...' }]
        }
      ]
    },
    labels: ['epic-label']  // Use labels instead of Epic Name for categorization
  }
};

Story 模板（SAFe 格式，Next-Gen）

// NOTE: Next-Gen uses 'parent' field, NOT customfield_10014
const story = {
  fields: {
    project: { key: 'PROJECT_KEY' },
    issuetype: { name: 'Story' },
    summary: '[US-ID]: As a [persona], I want [goal], so that [benefit]',
    description: {
      type: 'doc',
      version: 1,
      content: [
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'User Story' }]
        },
        {
          type: 'paragraph',
          content: [
            { type: 'text', text: 'As a ', marks: [{ type: 'strong' }] },
            { type: 'text', text: '[persona]' },
            { type: 'text', text: ', I want ', marks: [{ type: 'strong' }] },
            { type: 'text', text: '[goal]' },
            { type: 'text', text: ', so that ', marks: [{ type: 'strong' }] },
            { type: 'text', text: '[benefit]' }
          ]
        },
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'Acceptance Criteria' }]
        },
        {
          type: 'heading',
          attrs: { level: 3 },
          content: [{ type: 'text', text: 'Scenario 1: [Name]' }]
        },
        {
          type: 'bulletList',
          content: [
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'GIVEN [precondition]', marks: [{ type: 'strong' }] }] }]
            },
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'WHEN [action]', marks: [{ type: 'strong' }] }] }]
            },
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: 'THEN [expected result]', marks: [{ type: 'strong' }] }] }]
            }
          ]
        },
        {
          type: 'heading',
          attrs: { level: 2 },
          content: [{ type: 'text', text: 'Definition of Done' }]
        },
        {
          type: 'bulletList',
          content: [
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: '[ ] Code reviewed and approved' }] }]
            },
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: '[ ] Unit tests written and passing' }] }]
            },
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: '[ ] Integration tests passing' }] }]
            },
            {
              type: 'listItem',
              content: [{ type: 'paragraph', content: [{ type: 'text', text: '[ ] Documentation updated' }] }]
            }
          ]
        }
      ]
    },
    // Next-Gen: Link to parent Epic using 'parent' field
    parent: { key: 'EPIC_KEY' },
    labels: ['category-label', 'epic-id']
  }
};

Subtask 模板（Next-Gen）

// NOTE: Next-Gen uses 'Subtask' (no hyphen), NOT 'Sub-task'
const subtask = {
  fields: {
    project: { key: 'PROJECT_KEY' },
    issuetype: { name: 'Subtask' },  // Next-Gen: 'Subtask', Classic: 'Sub-task'
    summary: '[Technical task description]',
    // Parent Story (required for subtasks)
    parent: { key: 'STORY_KEY' }
    // Note: Description is optional for subtasks
  }
};

API 实现（Next-Gen 项目）

创建包含 Story 的 Epic（Next-Gen）

async function createEpicWithStories(epicFields, storyDefinitions) {
  const headers = {
    'Authorization': `Basic ${Buffer.from(`${EMAIL}:${TOKEN}`).toString('base64')}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  };

  // 1. Create Epic
  const epicResponse = await fetch(`${JIRA_URL}/rest/api/3/issue`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ fields: epicFields })
  });

  if (!epicResponse.ok) {
    const error = await epicResponse.text();
    throw new Error(`Epic creation failed: ${error}`);
  }

  const createdEpic = await epicResponse.json();
  console.log(`Created Epic: ${createdEpic.key}`);

  // 2. Create Stories linked to Epic using 'parent' field (Next-Gen)
  const createdStories = [];
  for (const storyDef of storyDefinitions) {
    const storyFields = {
      ...storyDef,
      parent: { key: createdEpic.key }  // Next-Gen: use 'parent', NOT customfield_10014
    };

    const storyResponse = await fetch(`${JIRA_URL}/rest/api/3/issue`, {
      method: 'POST',
      headers,
      body: JSON.stringify({ fields: storyFields })
    });

    if (!storyResponse.ok) {
      const error = await storyResponse.text();
      console.error(`Story creation failed: ${error}`);
      continue;
    }

    const createdStory = await storyResponse.json();
    createdStories.push(createdStory);
    console.log(`  Created Story: ${createdStory.key}`);

    // Rate limiting
    await new Promise(r => setTimeout(r, 100));
  }

  return { epic: createdEpic, stories: createdStories };
}

创建包含 Subtask 的 Story（Next-Gen）

async function createStoryWithSubtasks(storyFields, epicKey, subtaskSummaries) {
  const headers = {
    'Authorization': `Basic ${Buffer.from(`${EMAIL}:${TOKEN}`).toString('base64')}`,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  };

  // 1. Create Story under Epic
  const storyRequest = {
    fields: {
      ...storyFields,
      parent: { key: epicKey }  // Link to Epic
    }
  };

  const storyResponse = await fetch(`${JIRA_URL}/rest/api/3/issue`, {
    method: 'POST',
    headers,
    body: JSON.stringify(storyRequest)
  });

  if (!storyResponse.ok) {
    throw new Error(`Story creation failed: ${await storyResponse.text()}`);
  }

  const createdStory = await storyResponse.json();

  // 2. Create Subtasks under Story
  const createdSubtasks = [];
  for (const summary of subtaskSummaries) {
    const subtaskResponse = await fetch(`${JIRA_URL}/rest/api/3/issue`, {
      method: 'POST',
      headers,
      body: JSON.stringify({
        fields: {
          project: { key: storyFields.project.key },
          issuetype: { name: 'Subtask' },  // Next-Gen: 'Subtask', NOT 'Sub-task'
          summary: summary,
          parent: { key: createdStory.key }
        }
      })
    });

    if (subtaskResponse.ok) {
      createdSubtasks.push(await subtaskResponse.json());
    }

    await new Promise(r => setTimeout(r, 50));  // Rate limiting
  }

  return { story: createdStory, subtasks: createdSubtasks };
}

获取 Epic Link 字段 ID

Epic Link 字段因 Jira 实例而异。查找方法如下：

async function findEpicLinkField() {
  const response = await fetch(`${JIRA_URL}/rest/api/3/field`, { headers });
  const fields = await response.json();

  const epicLinkField = fields.find(f =>
    f.name === 'Epic Link' ||
    f.name.toLowerCase().includes('epic link')
  );

  return epicLinkField?.id; // Usually customfield_10014
}

批量删除 Issue

async function bulkDeleteIssues(projectKey, maxResults = 100) {
  // Search for all issues
  const jql = encodeURIComponent(`project = ${projectKey} ORDER BY key ASC`);
  const searchResponse = await fetch(
    `${JIRA_URL}/rest/api/3/search/jql?jql=${jql}&maxResults=${maxResults}&fields=key`,
    { headers }
  );
  const { issues } = await searchResponse.json();

  // Delete each issue
  for (const issue of issues) {
    await fetch(`${JIRA_URL}/rest/api/3/issue/${issue.key}?deleteSubtasks=true`, {
      method: 'DELETE',
      headers
    });
    console.log(`Deleted: ${issue.key}`);
    await new Promise(r => setTimeout(r, 100)); // Rate limit
  }

  return issues.length;
}

SAFe 最佳实践

Epic 命名

• 格式：[领域] - [业务成果]
• 示例：Marketing Copilot - Enable 24/7 Brand-Aware Content Generation

Story 命名（INVEST 标准）

• Independent：可独立开发
• Negotiable：细节可讨论
• Valuable：能带来用户价值
• Estimable：可估算规模
• Small：适合在一个 Sprint 内完成
• Testable：具有明确的验收标准

Story 格式

As a [specific persona],
I want [concrete action/capability],
So that [measurable benefit].

验收标准（Given-When-Then）

Scenario: [Descriptive name]
GIVEN [initial context/precondition]
WHEN [action/event occurs]
THEN [expected outcome]
AND [additional outcome if needed]

Issue 链接类型（Next-Gen）

链接类型	使用场景	字段
Parent（Next-Gen）	Story → Epic	parent: { key: 'EPIC-KEY' }
Parent（Next-Gen）	Subtask → Story	parent: { key: 'STORY-KEY' }
Blocks/Is blocked by	依赖项	链接类型
Relates to	相关项	链接类型

仅适用于 Classic 项目：

链接类型	使用场景	字段
Epic Link	Story → Epic	customfield_10014
Epic Name	Epic 短名称	customfield_10011

按项目类型划分的自定义字段

Next-Gen（团队管理型）- SCRUM 项目

用途	方法
将 Story 关联到 Epic	parent: { key: 'EPIC-KEY' }
将 Subtask 关联到 Story	parent: { key: 'STORY-KEY' }
Subtask Issue 类型	issuetype: { name: 'Subtask' }

Classic（公司管理型）

字段	ID（典型值）	用途
Epic Link	customfield_10014	将 Story 关联到 Epic
Epic Name	customfield_10011	Epic 的短名称
Story Points	customfield_10016	估算
Sprint	customfield_10007	Sprint 分配

错误处理

async function safeJiraRequest(url, options = {}) {
  const response = await fetch(url, { ...options, headers });

  if (!response.ok) {
    const error = await response.text();
    throw new Error(`Jira API ${response.status}: ${error.substring(0, 200)}`);
  }

  if (response.status === 204) return null;
  return response.json();
}

参考资料

• SAFe 框架
• Jira REST API v3
• Atlassian 文档格式