write-story

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Write Story

编写故事

Invocation

调用方式

/write-story <project-id>

project-id
— TrackerBoot 프로젝트 ID (필수)

project-id

없이 호출되면 Step 0에서 즉시 중단한다.

/write-story <project-id>

project-id
— TrackerBoot 项目 ID （必填）

如果调用时未提供

project-id

，则会在Step 0立即中止执行。

Step 0: 사전 조건 확인

Step 0：前置条件检查

스킬 실행 전 반드시 다음을 확인한다.

执行技能前必须确认以下内容：

프로젝트 ID 확인 (필수)

确认项目ID（必填）

호출 시

project-id

가 제공되었는지 확인한다.

제공되지 않았으면 즉시 중단:

❌ TrackerBoot 프로젝트 ID가 필요합니다.

프로젝트 ID 없이 실행하면 권한이 있는 임의의 프로젝트에 스토리가 등록될 수 있습니다.

사용법: /write-story <project-id>
예시:   /write-story 12345678

STOP.

제공되었으면:

project-id

를 세션 전체에서 사용할 값으로 저장한다.

检查调用时是否提供了

project-id

。

未提供则立即中止：

❌ 需要提供TrackerBoot项目ID。

如果未携带项目ID执行，故事可能会被注册到任意你有权限的项目中。

使用方法: /write-story <project-id>
示例:   /write-story 12345678

终止执行。

已提供则： 将

project-id

保存为整个会话可用的全局值。

persona.md 확인 (필수)

确认persona.md（必填）

.agents/skills/write-story/references/persona.md

존재 여부를 확인한다.

파일이 없으면 즉시 중단:

❌ 페르소나 정보가 없습니다.

사용자 스토리는 구체적인 페르소나 없이 작성할 수 없습니다.
먼저 `.agents/skills/write-story/references/persona.md` 파일을 작성해주세요.

STOP.

파일이 있으면: 페르소나 목록을 로드한다.

检查

.agents/skills/write-story/references/persona.md

是否存在。

文件不存在则立即中止：

❌ 缺少角色信息。

没有具体的角色设定无法编写用户故事。
请先编写`.agents/skills/write-story/references/persona.md`文件。

终止执行。

文件存在则： 加载角色列表。

Step 1: 시나리오 수집

Step 1：场景收集

사전 조건이 모두 통과되면, 사용자에게 시나리오를 요청한다.

구상하고 계신 사용자 시나리오를 설명해주세요.

누가 어떤 상황에서 무엇을 하려는지 자유롭게 서술해주시면 됩니다.
하나의 시나리오를 작은 스토리들로 나눠드리겠습니다.

예시:
  "쇼핑몰에서 사용자가 상품을 장바구니에 담고, 결제 수단을 선택한 뒤,
   주문을 완료하고 확인 이메일을 받는 전체 흐름"

PAUSE.

所有前置条件校验通过后，向用户请求场景信息。

请描述你构思的用户场景。

你可以自由描述谁在什么场景下想要做什么，
我会将单个场景拆分为多个小故事。

示例:
  "用户在电商网站将商品加入购物车，选择支付方式后完成订单，收到确认邮件的完整流程"

暂停等待用户输入。

Step 2: 스토리 분리

Step 2：故事拆分

수집한 시나리오를 분석하여 INVEST 원칙에 따라 독립적인 스토리들로 나눈다.

分析收集到的场景，按照INVEST原则拆分为独立的故事。

분리 기준

拆分标准

분리 상세 규칙은

.agents/skills/write-story/references/story-splitting-guide.md

참조.

각 스토리가 다음을 만족하는지 검토한다:

Independent: 다른 스토리에 의존하지 않고 독립적으로 전달 가능한가?
Valuable: 기술적 수평 분할이 아닌 사용자에게 실질적인 가치를 전달하는가?
Small: 하나의 이터레이션 안에서 완료할 수 있을 만큼 작은가?
Testable: 인수 기준을 작성할 수 있는가?

拆分详细规则参考

.agents/skills/write-story/references/story-splitting-guide.md

。

检查每个故事是否满足以下要求：

Independent：是否不依赖其他故事，可独立交付？
Valuable：是否不是技术层面的横向拆分，能够为用户传递实际价值？
Small：是否足够小，可以在单个迭代内完成？
Testable：是否可以编写对应的验收标准？

UI 인터랙션 흐름 시나리오일 때

若为UI交互流程场景

시나리오가 화면 구성, 버튼, 입력 폼 등 UI 조작 흐름을 포함하면 UI 인터랙션 흐름별 분리 패턴을 적용한다.

다음 유형별로 스토리를 나눈다:

진입점 노출 — 기능을 시작할 수 있는 버튼/아이콘이 화면에 보인다
화면 전환 — 버튼을 누르면 새 화면/윈도우가 열린다
폼 구성 확인 — 열린 화면에서 필요한 입력 필드와 버튼이 보인다
데이터 저장 — 입력 후 저장하면 결과가 특정 화면에 반영된다
취소/복귀 — 취소하거나 이전 버튼으로 되돌아간다
기존 데이터 노출 — 수정 진입 시 기존 값이 채워져 있다
삭제 확인 — 삭제 전 확인 메시지가 표시된다

"버튼 하나 추가"가 너무 작아 보여도, UI 인터랙션 흐름 단위에서는 유효한 스토리다.

如果场景包含页面布局、按钮、输入表单等UI操作流程，则适用UI交互流程拆分模式。

按以下类型拆分故事：

入口暴露 — 可开启功能的按钮/图标在页面上展示
页面跳转 — 点击按钮后打开新页面/窗口
表单结构确认 — 打开的页面展示所需的输入字段和按钮
数据存储 — 输入内容后保存，结果同步到对应页面
取消/返回 — 点击取消或返回按钮回到上一级页面
已有数据回显 — 进入编辑页时自动填充已有数据
删除确认 — 执行删除操作前弹出确认提示

哪怕看起来只是"添加一个按钮"这么小的需求，在UI交互流程单元中也是有效的故事。

분리 결과 표시 형식

拆分结果展示格式

undefined

undefined

📋 스토리 분리 결과

📋 故事拆分结果

시나리오를 [N]개의 스토리로 나눴습니다.

[1] [스토리 제목]

已将场景拆分为[N]个故事。

[1] [故事标题]

Why

需求背景

As [페르소나] I want [기능] So that [가치]

분리 이유: [왜 이 단위로 나눴는지]

[2] [스토리 제목]

As [角色] I want [功能] So that [价值]

拆分理由: [为何按该单元拆分的说明]

[2] [故事标题]

Why

需求背景

As [페르소나] I want [기능] So that [가치]

분리 이유: [왜 이 단위로 나눴는지]

...

이 분리가 적절한가요? → "ok" — 인수 기준 작성으로 진행 → "split [번호]" — 더 잘게 나누기 → "merge [번호] [번호]" — 합치기 → "edit [번호]" — 수정


PAUSE. 변경 사항 반영 후 재표시. "ok" 를 받으면 진행.

---

As [角色] I want [功能] So that [价值]

拆分理由: [为何按该单元拆分的说明]

...

请问拆分结果是否合适？ → 回复"ok" — 进入验收标准编写环节 → 回复"split [编号]" — 对指定故事做更细拆分 → 回复"merge [编号] [编号]" — 合并指定故事 → 回复"edit [编号]" — 修改指定故事


暂停等待用户输入，修改后重新展示结果。收到"ok"回复后进入下一环节。

---

Step 3: 인수 기준 작성

Step 3：编写验收标准

확정된 모든 스토리에 대해 AC를 한 번에 작성한 뒤, 전체를 함께 검토한다.

为所有确认后的故事一次性编写AC，再统一进行审核。

AC 작성 순서

AC编写顺序

각 스토리마다 다음 순서로 작성한다:

해피 패스 — 정상적인 주요 흐름 먼저
엣지 케이스 — 경계값, 예외 흐름
오류 케이스 — 잘못된 입력, 시스템 오류

每个故事按以下顺序编写：

正常路径 — 优先编写核心的正常操作流程
边界用例 — 边界值、异常流程
错误用例 — 非法输入、系统错误

UI 스토리 AC 작성 시 규칙

UI故事AC编写规则

GIVEN: 항상 화면 이름을 명시한다 (예: "메인 화면이 열려 있을 때")
THEN: 화면의 어느 위치에서 무엇이 보이는지 명시한다 (예: "오른쪽 상단에 + 버튼이 보인다")
상세 규칙은
```
ac-writing-guide.md
```
의 "UI 스토리 AC 작성 패턴" 참조

GIVEN：必须明确页面名称（例如："当主页面已打开时"）
THEN：必须明确页面位置和展示内容（例如："右上角展示+按钮"）
详细规则参考
```
ac-writing-guide.md
```
中的"UI故事AC编写模式"

영속성 AC

持久化AC

데이터를 생성·수정·삭제하는 스토리에는 반드시 영속성 AC를 마지막에 추가한다. 별도 "영속성 스토리"를 만들지 않는다. 패턴은

ac-writing-guide.md

의 "영속성 AC 패턴" 참조

涉及数据创建、修改、删除的故事，必须在最后添加持久化AC，不需要单独创建"持久化故事"。模式参考

ac-writing-guide.md

中的"持久化AC模式"

전체 AC 표시 형식

完整AC展示格式

모든 스토리의 AC를 하나의 블록으로 표시한다.

markdown

undefined

将所有故事的AC合并为一个区块展示：

markdown

undefined

📋 인수 기준 초안 (전체 [N]개 스토리)

📋 验收标准初稿（共[N]个故事）

[1] [스토리 제목]

[1] [故事标题]

gherkin

Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

gherkin

Scenario: [场景名称]
    Given [前置条件]
    When  [用户操作]
    Then  [预期结果]

Scenario: [场景名称]
    Given [前置条件]
    When  [用户操作]
    Then  [预期结果]

[2] [스토리 제목]

[2] [故事标题]

gherkin

Scenario: [시나리오 이름]
    Given [사전 조건]
    When  [사용자 행동]
    Then  [기대되는 결과]

...


표시 후:

인수 기준을 검토해주세요. → "add [스토리번호] [내용]" — AC 추가 → "remove [스토리번호 AC번호]" — AC 제거 → "edit [스토리번호 AC번호]" — AC 수정 → "done" — 완료, 레이블 선택으로 진행


PAUSE. 변경 사항 반영 후 재표시. "done" 을 받으면 Step 4로 진행한다.

AC 작성 상세 규칙은 `.agents/skills/write-story/references/ac-writing-guide.md` 참조.

---

gherkin

Scenario: [场景名称]
    Given [前置条件]
    When  [用户操作]
    Then  [预期结果]

...


展示后提示：

请审核验收标准： → 回复"add [故事编号] [内容]" — 新增AC → 回复"remove [故事编号 AC编号]" — 删除AC → 回复"edit [故事编号 AC编号]" — 修改AC → 回复"done" — 完成，进入标签选择环节


暂停等待用户输入，修改后重新展示结果。收到"done"回复后进入Step 4。

AC编写详细规则参考`.agents/skills/write-story/references/ac-writing-guide.md`。

---

Step 4: 레이블 선택

Step 4：选择标签

4-1. 레이블 추천

4-1. 推荐标签

전체 스토리 내용을 분석하여 공통 레이블과 개별 레이블을 추천한다. 스토리 번호는

S1

S2

형식으로 표기하고, 연속된 범위는

S1~S4

형식으로 묶어 표시한다.

스토리 내용을 분석한 추천 레이블입니다.

공통 레이블 추천:
  - [레이블명]   ([적용 이유 — 기능 도메인 설명])
  - [레이블명]

개별 레이블 추천:
  - S[번호]~S[번호] : [레이블명]
  - S[번호]~S[번호] : [레이블명]
  - S[번호] : [레이블명]

적용할 레이블을 선택해주세요.
→ "ok" / "done" — 추천 그대로 확정
→ 추가/제거하고 싶으면 알려주세요

PAUSE. 변경 사항 반영 후 재표시. "ok" / "done" 을 받으면 레이블을 확정하고 4-2로 진행한다.

分析所有故事内容，推荐公共标签和独立标签。故事编号用

S1

、

S2

格式表示，连续范围用

S1~S4

格式合并展示：

以下是分析故事内容后推荐的标签：

公共标签推荐：
  - [标签名]   ([适用理由 — 功能域说明])
  - [标签名]

独立标签推荐：
  - S[编号]~S[编号] : [标签名]
  - S[编号]~S[编号] : [标签名]
  - S[编号] : [标签名]

请选择要应用的标签：
→ 回复"ok" / "done" — 直接确认推荐标签
→ 如需新增/删除标签请告知

暂停等待用户输入，修改后重新展示结果。收到"ok" / "done"回复后确认标签，进入4-2环节。

4-2. 관련 스토리 조회 및 문맥 반영

4-2. 查询关联故事并对齐上下文

레이블이 확정되면, TrackerBoot MCP로 동일 프로젝트 내 동일 레이블의 기존 스토리를 조회한다.

tracker-boot-mcp-tb_search_stories (projectId + labels filter)

조회 시 반드시 Step 0에서 저장한

project-id

를 함께 전달한다.

관련 스토리가 없으면: 조용히 진행한다.

관련 스토리가 있으면: 다음 순서로 분석한다.

标签确认后，通过TrackerBoot MCP查询同一项目下相同标签的已有故事：

tracker-boot-mcp-tb_search_stories (projectId + labels filter)

查询时必须携带Step 0保存的

project-id

。

无关联故事则： 静默进入下一环节。

有关联故事则： 按以下顺序分析：

1) 기존 스토리 목록 표시

1) 展示已有相关故事列表

📋 기존 관련 스토리 (레이블: "[레이블]", 총 [N]개)
- [스토리 ID] [스토리 제목]
- [스토리 ID] [스토리 제목]
...

기존 스토리를 바탕으로 문맥을 분석합니다...

📋 已有相关故事（标签："[标签]", 共[N]个）
- [故事ID] [故事标题]
- [故事ID] [故事标题]
...

正在基于已有故事分析上下文...

2) 문맥 분석

2) 上下文分析

기존 스토리들에서 다음 항목을 추출한다:

페르소나 표현 — "As a" 뒤에 쓰인 페르소나 명칭 (기존과 일치시킴)
동사/행동 표현 — "I want to" 뒤에 쓰인 동사 패턴 (기존 용어 우선)
화면·UI 용어 — 기존 스토리에서 사용한 화면 이름, 버튼 명칭
AC 형식 — GIVEN/WHEN/THEN 작성 스타일 및 상세 수준
중복 스코프 — 새 스토리와 동일하거나 겹치는 기능

从已有故事中提取以下内容：

角色表述 — "As a"后面的角色名称（与已有表述保持一致）
动词/行为表述 — "I want to"后面的动词模式（优先使用已有术语）
页面·UI术语 — 已有故事中使用的页面名称、按钮名称
AC格式 — GIVEN/WHEN/THEN的编写风格和详细程度
范围重叠 — 与新故事相同或重叠的功能范围

3) 변경이 필요한 경우 개발자에게 알림

3) 如需调整则告知开发者

분석 결과 새 스토리 조정이 필요하면 변경 사항을 표시하고 확인을 받는다:

🔍 기존 스토리 문맥 분석 결과

[변경 필요 항목이 있는 경우]

**조정 사항:**
- [스토리 N] "[기존 표현]" → "[기존 스토리 문맥에 맞춘 표현]"
  이유: [기존 스토리에서 사용한 용어/패턴과 일치시키기 위해]
- ...

[중복 스코프가 있는 경우]

**중복 검토:**
- [스토리 N]이 기존 스토리 [[스토리 ID] [제목]]과 스코프가 겹칩니다.
  → 제거 또는 스코프 조정이 필요합니다.

조정을 적용할까요?
→ "ok" — 전체 적용
→ "skip" — 조정 없이 진행
→ 특정 항목만 적용하려면 알려주세요

PAUSE. "ok" 를 받으면 스토리와 AC에 조정 사항을 반영하고 Step 5로 진행한다.

변경이 필요하지 않은 경우: 조용히 Step 5로 진행한다.

分析后发现新故事需要调整的，展示修改内容并请求确认：

🔍 已有故事上下文分析结果

[存在需要调整的内容时]

**调整项：**
- [故事N] "[原有表述]" → "[匹配已有故事上下文的表述]"
  理由：为了和已有故事使用的术语/模式保持一致
- ...

[存在范围重叠时]

**重叠检查：**
- [故事N]与已有故事[[故事ID] [标题]]范围重叠，
  需要删除或调整范围。

是否应用调整？
→ 回复"ok" — 应用全部调整
→ 回复"skip" — 不调整直接进入下一环节
→ 如需仅应用指定项请告知

暂停等待用户输入。收到"ok"回复后将调整项应用到故事和AC中，进入Step 5。

无需调整则： 静默进入Step 5。

Step 5: 최종 확인

Step 5：最终确认

완성된 전체 스토리 목록을 표시하고 최종 승인을 받는다.

markdown

undefined

展示完整的最终故事列表，请求最终确认：

markdown

undefined

✅ 최종 스토리 Preview ([N]개)

✅ 最终故事预览（共[N]个）

[1] [스토리 제목]

[1] [故事标题]

Why

需求背景

As [페르소나] I want [기능] So that [가치]

As [角色] I want [功能] So that [价值]

Acceptance Criteria

验收标准

gherkin

Scenario: [시나리오 이름]
    Given [조건]
    When  [행동]
    Then  [결과]

레이블: [레이블1], [레이블2]

gherkin

Scenario: [场景名称]
    Given [条件]
    When  [操作]
    Then  [结果]

标签： [标签1], [标签2]

[2] [스토리 제목]

[2] [故事标题]

...

TrackerBoot에 [N]개 스토리를 등록할까요? → "register" — 전체 등록 → "register [번호]" — 해당 스토리만 등록 → "edit [번호] [섹션]" — 수정 (title / description / ac / labels) → "cancel" — 취소


PAUSE.

---

...

是否将[N]个故事注册到TrackerBoot？ → 回复"register" — 注册全部 → 回复"register [编号]" — 仅注册指定故事 → 回复"edit [编号] [板块]" — 修改（可修改板块：title / description / ac / labels） → 回复"cancel" — 取消


暂停等待用户输入。

---

Step 6: TrackerBoot 등록

Step 6：注册到TrackerBoot

개발자가 확인하면 TrackerBoot MCP로 스토리를 **역순(마지막 스토리부터)**으로 등록한다.

TrackerBoot는 새로 등록된 스토리를 목록 상단에 추가하므로, 원하는 순서대로 화면에 표시되려면 마지막 스토리(S[N])부터 첫 번째 스토리(S1) 순서로 등록해야 한다.

开发者确认后，按**倒序（从最后一个故事开始）**将故事注册到TrackerBoot MCP。

TrackerBoot会将新注册的故事放在列表顶部，因此要按预期顺序展示，必须按**最后一个故事(S[N])到第一个故事(S1)**的顺序注册。

MCP 도구

MCP工具

tracker-boot-mcp-tb_create_story   — 스토리 생성
tracker-boot-mcp-tb_batch_create_tasks — 인수 기준(AC) 태스크 일괄 등록

tracker-boot-mcp-tb_create_story   — 创建故事
tracker-boot-mcp-tb_batch_create_tasks — 批量注册验收标准(AC)任务

등록 절차

注册流程

스토리마다 다음 2단계로 등록한다. S[N] → S[N-1] → ... → S[1] 순서로 진행한다.

1단계 — 스토리 생성:

라벨은 MCP가 지원하지 않으므로

description

의

**Notes:**

섹션에 ul 형식으로 포함한다. 추후 MCP 서버가 라벨 생성을 지원하면

labels

파라미터를 함께 전달한다.

json

{
  "projectId": "[Step 0에서 저장한 project-id]",
  "title": "[스토리 제목]",
  "storyType": "Feature",
  "description": "### Why\n\n**As** [페르소나]\n**I want** [기능]\n**So that** [가치]\n\n**Notes:**\n\n- [레이블1]\n- [레이블2]"
}

2단계 — 인수 기준 태스크 등록 (1단계에서 반환된 storyId 사용):

json

{
  "storyId": "[생성된 스토리 ID]",
  "titles": [
    "GIVEN [조건] WHEN [행동] THEN [결과]",
    "GIVEN [조건] WHEN [행동] THEN [결과]"
  ]
}

每个故事分两步注册，按S[N] → S[N-1] → ... → S[1]的顺序执行：

第一步 — 创建故事：

当前MCP不支持标签，因此将标签以无序列表形式放在

description

的

**Notes:**

板块中。后续MCP服务支持标签创建后，再同步传递

labels

参数。

json

{
  "projectId": "[Step 0保存的project-id]",
  "title": "[故事标题]",
  "storyType": "Feature",
  "description": "### 需求背景\
\
**As** [角色]\
**I want** [功能]\
**So that** [价值]\
\
**Notes:**\
\
- [标签1]\
- [标签2]"
}

第二步 — 注册验收标准任务（使用第一步返回的storyId）：

json

{
  "storyId": "[已生成的故事ID]",
  "titles": [
    "GIVEN [条件] WHEN [操作] THEN [结果]",
    "GIVEN [条件] WHEN [操作] THEN [结果]"
  ]
}

등록 진행 표시

注册进度展示

역순으로 진행하되, 진행 카운터는 원래 순서(S1=1번)로 표시한다:

⏳ [N/N] 등록 중... [마지막 스토리 제목]
✅ [N/N] [마지막 스토리 제목] — 완료 (ID: [스토리 ID])
⏳ [N-1/N] 등록 중... [N-1번째 스토리 제목]
✅ [N-1/N] [N-1번째 스토리 제목] — 완료 (ID: [스토리 ID])
...
⏳ [1/N] 등록 중... [첫 번째 스토리 제목]
✅ [1/N] [첫 번째 스토리 제목] — 완료 (ID: [스토리 ID])

虽然按倒序执行，但进度计数器按原始顺序展示（S1=第1个）：

⏳ [N/N] 注册中... [最后一个故事标题]
✅ [N/N] [最后一个故事标题] — 注册完成（ID: [故事ID]）
⏳ [N-1/N] 注册中... [第N-1个故事标题]
✅ [N-1/N] [第N-1个故事标题] — 注册完成（ID: [故事ID]）
...
⏳ [1/N] 注册中... [第一个故事标题]
✅ [1/N] [第一个故事标题] — 注册完成（ID: [故事ID]）

전체 등록 완료

全部注册完成

✅ 전체 [N]개 스토리 등록 완료

등록된 스토리:
  - #[스토리 ID] [스토리 제목]
  - #[스토리 ID] [스토리 제목]
  ...

→ /tdd-plan <project-id> <story-id> 로 각 스토리의 TDD 세션을 시작할 수 있습니다.

✅ 共[N]个故事全部注册完成

已注册故事：
  - #[故事ID] [故事标题]
  - #[故事ID] [故事标题]
  ...

→ 可通过/tdd-plan <project-id> <story-id> 启动对应故事的TDD会话。

등록 실패

注册失败

특정 스토리 등록에 실패하면:

❌ [N번 스토리] 등록 실패: [오류 메시지]

→ "retry" — 다시 시도
→ "skip" — 이 스토리 건너뛰고 다음으로
→ "copy" — 해당 스토리 내용을 Markdown 형식으로 출력
→ "cancel" — 전체 등록 중단

如果某个故事注册失败：

❌ [第N个故事] 注册失败: [错误信息]

→ 回复"retry" — 重试
→ 回复"skip" — 跳过该故事，继续注册下一个
→ 回复"copy" — 以Markdown格式输出该故事内容
→ 回复"cancel" — 终止全部注册流程

참조 파일

参考文件

파일	사용 시점
`.agents/skills/write-story/references/story-splitting-guide.md`	Step 2 스토리 분리 시
`.agents/skills/write-story/references/story-format-guide.md`	Step 2 스토리 초안 형식
`.agents/skills/write-story/references/ac-writing-guide.md`	Step 3 AC 작성 시

文件路径	使用场景
`.agents/skills/write-story/references/story-splitting-guide.md`	Step 2 拆分故事时
`.agents/skills/write-story/references/story-format-guide.md`	Step 2 故事初稿格式参考
`.agents/skills/write-story/references/ac-writing-guide.md`	Step 3 编写AC时
",