atlassian-templates

Atlassian 模板与文件创建专家

专注于为 Jira 和 Confluence 创建、修改和管理可复用的模板与文件。确保一致性，加快内容创建速度，并维护全组织范围的标准。

---

工作流

模板创建流程

1. 发现：访谈利益相关方，了解需求
2. 分析：审查现有内容模式
3. 设计：创建模板结构和占位符
4. 实现：使用宏和格式构建模板
5. 测试：使用示例数据进行验证，确认模板在预览中渲染正确后再发布
6. 文档化：编写使用说明
7. 发布：通过 MCP 部署到合适的空间/项目（参见下文 MCP 操作）
8. 验证：确认部署成功；如出现错误，回滚到之前的版本
9. 培训：对用户进行模板使用培训
10. 监控：跟踪采用情况并收集反馈
11. 迭代：根据使用情况进行优化

模板修改流程

1. 评估：审查变更请求及其影响
2. 版本化：创建新版本，保留旧版本可用
3. 修改：更新模板结构/内容
4. 测试：验证变更不会破坏现有用法；发布前预览更新后的模板
5. 迁移：为现有内容提供迁移路径
6. 沟通：向用户通报变更
7. 支持：协助用户完成迁移
8. 归档：过渡结束后弃用旧版本；确认已弃用的模板已取消列出，而非删除

蓝图开发

1. 定义蓝图的范围和目的
2. 设计多页面结构
3. 为每个部分创建页面模板
4. 配置页面创建规则
5. 添加动态内容（Jira 查询、用户数据）
6. 使用示例空间对蓝图创建流程进行端到端测试
7. 部署前验证所有宏引用均可正确解析
8. 移交给：Atlassian 管理员进行全局部署

---

Confluence 模板库

模板设计模式参见 references/template-design-patterns.md，治理模型参见 references/governance-framework.md。如需可直接部署的存储格式标记，请使用随附的脚手架工具（参见下文 模板脚手架）。以下概述了本技能创建和维护的标准模板类型。

Confluence 模板类型

模板	用途	使用的主要宏
会议纪要	包含议程、决策和行动项的结构化会议记录	{date}、{tasks}、{panel}、{info}、{note}
项目章程	组织层面的项目范围、利益相关方 RACI、时间线和预算	{panel}、{status}、{timeline}、{info}
Sprint 回顾	敏捷仪式模板，包含做得好的 / 做得不好的 / 行动项	{panel}、{expand}、{tasks}、{status}
PRD	功能定义，包含目标、用户故事、功能性与非功能性需求以及发布计划	{panel}、{status}、{jira}、{warning}
决策日志	结构化的方案分析，包含决策矩阵和实施跟踪	{panel}、{status}、{info}、{tasks}

标准章节，包含在所有 Confluence 模板中：

• 包含元数据（负责人、日期、状态）的页眉面板
• 带有行内占位符说明的清晰标注内容章节
• 使用 {tasks} 宏的行动项区块
• 相关链接和参考资料

完整示例：会议纪要模板

格式警告：以下示例使用的是旧版 Wiki 标记语言（{panel}、h2.、{tasks}），仅为便于阅读而展示。Wiki 标记语言不是 Confluence 存储格式，mcp__atlassian__createConfluencePage / updateConfluencePage 需要的是存储格式（XHTML、<ac:structured-macro> 元素）或 ADF，因此会拒绝此格式。要获取可直接用于部署的存储格式版本，请运行脚手架工具：python3 scripts/template_scaffolder.py meeting-notes（参见模板脚手架工具）。

{panel:title=Meeting Metadata|borderColor=#0052CC|titleBGColor=#0052CC|titleColor=#FFFFFF}
*Date:* {date}
*Owner / Facilitator:* @[facilitator name]
*Attendees:* @[name], @[name]
*Status:* {status:colour=Yellow|title=In Progress}
{panel}

h2. Agenda
# [Agenda item 1]
# [Agenda item 2]
# [Agenda item 3]

h2. Discussion & Decisions
{panel:title=Key Decisions|borderColor=#36B37E|titleBGColor=#36B37E|titleColor=#FFFFFF}
* *Decision 1:* [What was decided and why]
* *Decision 2:* [What was decided and why]
{panel}

{info:title=Notes}
[Detailed discussion notes, context, or background here]
{info}

h2. Action Items
{tasks}
* [ ] [Action item] — Owner: @[name] — Due: {date}
* [ ] [Action item] — Owner: @[name] — Due: {date}
{tasks}

h2. Next Steps & Related Links
* Next meeting: {date}
* Related pages: [link]
* Related Jira issues: {jira:key=PROJ-123}

其他内置类型（decision-log、runbook、project-kickoff）的存储格式示例可通过 python3 scripts/template_scaffolder.py --list 获取；其余类型（Project Charter、Sprint Retrospective、PRD）的设计模式请参见 references/template-design-patterns.md。

---

Jira 模板库

Jira 模板类型

模板	用途	主要章节
用户故事	采用 As a / I want / So that 格式的功能请求	验收标准（Given/When/Then）、设计链接、技术说明、完成定义
缺陷报告	记录缺陷及复现步骤	环境、复现步骤、预期行为与实际行为、严重程度、变通方案
Epic	高层级计划范围	愿景、目标、成功指标、故事拆解、依赖项、时间线

所有 Jira 模板均包含标准章节：

• 清晰的摘要行
• 以复选框形式列出的验收标准或成功标准
• 相关事项和依赖项部分
• 完成定义（适用于故事）

---

宏使用指南

动态内容：使用宏自动更新内容（日期、用户提及、Jira 查询） 视觉层级：使用 {panel}、{info} 和 {note} 创建视觉区分 交互性：在较长的模板中使用 {expand} 创建可折叠章节 集成：通过 {jira} 宏嵌入 Jira 图表和表格，以显示实时数据

---

模板脚手架工具 — 生成存储格式标记

附带的脚手架工具会生成 Confluence 存储格式 XHTML——这是 createConfluencePage / updateConfluencePage 接受的精确正文格式，也是此技能的规范部署方式：

# List available template types (meeting-notes, decision-log, runbook, project-kickoff, custom)
python3 scripts/template_scaffolder.py --list

# Generate a template body (storage-format XHTML)
python3 scripts/template_scaffolder.py meeting-notes

# Custom template with chosen sections and macros, JSON output for programmatic use
python3 scripts/template_scaffolder.py custom --sections "Overview,Goals,Action Items" --macros "toc,status,info" --format json

使用输出时，请提取 CONFLUENCE STORAGE FORMAT MARKUP 区块（文本模式）或标记字段（JSON 模式），并将其原样作为 body 传递给 mcp__atlassian__createConfluencePage。之后通过 Confluence UI 应用建议的标签（MCP 不提供标签工具）。

Atlassian MCP 集成

主要工具：Atlassian 远程 MCP 服务（随附 .mcp.json，服务键为 atlassian）。工具以 mcp__atlassian__<toolName>（camelCase）形式提供。规范工具列表：project-management/references/atlassian-mcp-tools.md。切勿臆造工具名称——如果某项功能不在该列表中，则无法通过 MCP 使用；请改用 Web UI 或 REST API。

通过 MCP 进行模板操作

先通过 mcp__atlassian__getAccessibleAtlassianResources 获取一次 cloudId。将尖括号占位符替换为实际值;调用时请从各工具的 schema 中确认准确的参数名。

创建 Confluence 模板页面(正文来自上述脚手架):

mcp__atlassian__createConfluencePage (cloudId, space, title="Template: Meeting Notes",
  body=<storage-format XHTML from template_scaffolder.py>, parent page id optional)

标签(template、meeting-notes)必须在 Confluence 界面中添加——MCP 没有标签工具。

更新现有模板页面(先读取以获取当前版本):

mcp__atlassian__getConfluencePage (cloudId, pageId=<existing page id>)
mcp__atlassian__updateConfluencePage (cloudId, pageId=<id>, version=<current + 1>,
  body=<updated storage-format content>)

Jira 问题描述模板:没有用于字段配置的 MCP 工具(描述字段上的 default_value、屏幕、字段上下文)。请在 Jira 管理界面(Settings > Issues > Field configurations)中配置描述默认值,或通过 REST(/rest/api/3/fieldconfiguration)配置。MCP 能做的是:通过 mcp__atlassian__createJiraIssue 创建预填模板文本的问题(将模板正文作为描述传入),并通过 mcp__atlassian__getJiraIssueTypeMetaWithFields 查看每种问题类型的必填字段。

真正的 Confluence 模板/蓝图同样无法通过 MCP 创建——createConfluencePage 创建的是普通页面,可作为复制来源的模板使用。要注册真正的空间模板,请在界面中使用 Space settings > Templates。

将模板页面批量部署到多个空间:

# Repeat per target space:
mcp__atlassian__createConfluencePage (cloudId, space=<target>, title="Template: Meeting Notes", body=<storage-format content>)
# Verify each create before proceeding:
mcp__atlassian__getConfluencePage (cloudId, pageId=<id returned by create>)
# Assert the returned body is non-empty and contains the expected <ac:structured-macro> elements

部署后的验证检查点:

• 通过 mcp__atlassian__getConfluencePage 获取已创建/更新的页面,并确认其渲染时没有宏错误
• 检查 Jira 宏嵌入内容是否能在目标 Jira 项目中正确解析
• 确认已发布视图中的任务块可以交互
• 若任一检查失败:使用 mcp__atlassian__updateConfluencePage 回滚,参数为 version: <current + 1> 并附上之前版本的正文

---

最佳实践与治理

组织特定标准:

• 在页面头部的版本说明中记录模板版本
• 归档前用 {warning} 横幅标记过时模板;归档而非删除
• 为每个模板维护链接的使用指南
• 按季度评审周期收集反馈;在弃用前纳入使用指标

质量门禁(每次部署前应用):

• 为每个章节提供示例内容
• 在预览中使用示例数据测试
• 在变更日志中添加版本注释
• 已配置反馈机制(启用评论或链接调查问卷)

治理流程:

1. 申请与理由说明
2. 设计与评审
3. 与试点用户测试
4. 文档编写
5. 审批
6. 部署(通过 MCP 或手动)
7. 培训
8. 监控

---

交接协议

交接摘要(治理背景见 references/governance-framework.md):

合作方	接收自	发送至
Senior PM	模板需求、报告模板、高管格式	完成的模板、使用分析、优化建议
Scrum Master	冲刺仪式需求、团队特定请求、回顾格式偏好	可直接用于冲刺的模板、敏捷仪式结构、速度追踪模板
Jira Expert	问题模板需求、自定义字段显示需求	问题描述模板、字段配置模板、JQL 查询模板
Confluence Expert	空间特定需求、全局模板请求、蓝图需求	已配置的页面模板、蓝图结构、部署计划
Atlassian Admin	组织级标准、全局部署需求、合规模板	待审批的全局模板、使用报告、合规状态