bf-lead-implement

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lead Implement (Monitor Pattern)

Lead 实现（Monitor 模式）

Overview

概述

에픽 내 모든 Story의 TDD 구현을 조율하는 Lead 스킬이다. 모든 난이도의 Story를 agent에게 위임하고 Lead는 코드를 직접 만지지 않는다. sprint-status.yaml은 이 Lead만 갱신한다 (단일 쓰기 지점).

这是协调Epic内所有Story的TDD实现的Lead技能。将所有难度的Story委托给Agent处理，Lead不直接编写代码。仅由该Lead更新sprint-status.yaml（单一写入点）。

When to Use

使用场景

```
bf-lead-orchestrate
```
가 에픽 루프에서 스폰
직접 호출하지 않는다.

由
```
bf-lead-orchestrate
```
在Epic循环中生成
不直接调用

Prerequisites

前置条件

Story 파일:
```
docs/stories/{TICKET}-story-*.md
```
(현재 에픽 소속)
```
docs/sprint-status.yaml
```
```
docs/conventions.md
```
(있으면)
수정 재실행인 경우:
```
docs/reviews/{EPIC-ID}-modification.md
```
(사람의 수정 지시)

Story文件：
```
docs/stories/{TICKET}-story-*.md
```
（当前属于该Epic）
```
docs/sprint-status.yaml
```
```
docs/conventions.md
```
（如果存在）
若为修改重跑：
```
docs/reviews/{EPIC-ID}-modification.md
```
（人工修改指示）

Error Handling

错误处理

S/M Story agent 스폰 실패: 1회 재시도 후에도 실패 시 해당 Story를 stuck으로 처리 (
```
status: in_progress
```
설정 후 stuck.md에 "agent spawn failed" 기록,
```
ralph_stuck: true
```
설정). Done 신호에서
```
"done (stuck: {STORY-ID})"
```
목록에 포함하여 orchestrate가
```
skipped
```
로 처리
L/XL Story Sub-Lead 스폰 실패: 단독 Sonnet agent로 fallback (S/M과 동일 방식)
sprint-status.yaml 쓰기 실패: CLAUDE.md의 Read-yq-Verify Recover 절차를 따른다 (git checkout → 1회 재시도 → 실패 시 orchestrate에
```
"error: sprint-status update failed"
```
보고)

S/M Story Agent生成失败：重试1次仍失败则将该Story标记为stuck（设置
```
status: in_progress
```
后在stuck.md中记录"agent spawn failed"，设置
```
ralph_stuck: true
```
）。在Done信号的
```
"done (stuck: {STORY-ID})"
```
列表中包含该Story，以便orchestrate将其标记为
```
skipped
```
L/XL Story Sub-Lead生成失败：回退为使用单个Sonnet Agent（与S/M处理方式相同）
sprint-status.yaml写入失败：遵循CLAUDE.md中的Read-yq-Verify恢复流程（git checkout → 重试1次 → 失败则向orchestrate报告
```
"error: sprint-status update failed"
```
）

Instructions

操作步骤

1. 초기 로딩

1. 初始加载

yq 전제조건 체크 (최초 1회):

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

현재 에픽에 속한 모든 Story 문서를 읽는다.
```
docs/conventions.md
```
를 읽는다.
수정 재실행인 경우:
```
modification.md
```
를 읽어 수정 지시와 대상 Story를 확인한다.
```
docs/sprint-status.yaml
```
을 읽어서 각 Story의 난이도와 상태를 확인한다.
- ```
status: done
```
  인 Story는 건너뛴다.
- ```
status: todo
```
  또는
```
in_progress
```
  인 Story만 대상으로 한다.

yq前置条件检查（仅首次执行）：

bash

command -v yq >/dev/null 2>&1 || { echo "❌ yq not installed. Install: brew install yq"; exit 1; }

读取当前Epic下的所有Story文档。
读取
```
docs/conventions.md
```
。
若为修改重跑：读取
```
modification.md
```
确认修改指示和目标Story。
读取
```
docs/sprint-status.yaml
```
确认每个Story的难度和状态：
- 跳过
```
status: done
```
  的Story。
- 仅处理
```
status: todo
```
  或
```
in_progress
```
  的Story。

1b. Convention 섹션 필터링

1b. 规约章节过滤

conventions.md를 읽은 후, 각 Story에 전달할 관련 섹션을 결정한다.

Core 섹션 (항상 포함): 아키텍처, 네이밍, 테스트, 코드 스타일

Concern-area 섹션 (Story 파일 경로 기반 필터링):

Story 파일 경로 패턴	포함 섹션
`src/components/` , `src/pages/` , `src/views/` , `src/layouts/` , `src/hooks/` , `.tsx` , `.vue` , `*.svelte` , `app/` (Next.js)	UI 패턴
`src/api/` , `src/routes/` , `src/controllers/` , `src/middleware/` , `routes/` , `controllers/` , `server/`	API 패턴
`src/models/` , `src/entities/` , `src/repositories/` , `prisma/` , `migrations/` , `src/db/` , `drizzle/`	DB 패턴
`src/auth/` , `src/security/` , `src/guards/` , `middleware/auth*`	보안 패턴
`Dockerfile` , `.github/` , `docker-compose` , `infra/` , `deploy/` , `.env`	인프라 패턴

필터링 규칙:

conventions.md에 concern-area 섹션이 없으면 전체 내용을 그대로 전달한다 (하위 호환).
Story의 Technical Notes에 변경 대상 파일이 없으면 전체 내용을 전달한다 (안전 fallback).
매칭되는 concern-area 섹션이 있으면, Core 섹션 + 매칭 concern-area 섹션만 추출하여 인라인으로 전달한다.
각
```
##
```
헤딩부터 다음
```
##
```
헤딩 전까지를 하나의 섹션으로 취급한다.

인라인 전달 형식:

[Project Conventions]
아래는 이 Story에 관련된 프로젝트 컨벤션이다. 전체 컨벤션은 Epic 리뷰 시 Convention Guard가 검사한다.

{추출된 섹션 내용}

[Library Reference]
아래는 이 Story 구현에 참고할 라이브러리 API 레퍼런스이다. 프로젝트 컨벤션과 충돌 시 컨벤션을 우선한다.

读取conventions.md后，确定要传递给每个Story的相关章节。

核心章节（始终包含）： 架构、命名、测试、代码风格

关注领域章节（基于Story文件路径过滤）：

Story文件路径模式	包含章节
`src/components/` , `src/pages/` , `src/views/` , `src/layouts/` , `src/hooks/` , `.tsx` , `.vue` , `*.svelte` , `app/` (Next.js)	UI模式
`src/api/` , `src/routes/` , `src/controllers/` , `src/middleware/` , `routes/` , `controllers/` , `server/`	API模式
`src/models/` , `src/entities/` , `src/repositories/` , `prisma/` , `migrations/` , `src/db/` , `drizzle/`	DB模式
`src/auth/` , `src/security/` , `src/guards/` , `middleware/auth*`	安全模式
`Dockerfile` , `.github/` , `docker-compose` , `infra/` , `deploy/` , `.env`	基础设施模式

过滤规则：

若conventions.md中无关注领域章节，则直接传递全部内容（向下兼容）。
若Story的Technical Notes中无目标修改文件，则传递全部内容（安全回退）。
若存在匹配的关注领域章节，则仅提取核心章节+匹配的关注领域章节，以内联方式传递。
将每个
```
##
```
标题到下一个
```
##
```
标题前的内容视为一个章节。

内联传递格式：

[项目规约]
以下是与该Story相关的项目规约。完整规约将由Epic评审时的Convention Guard进行检查。

{提取的章节内容}

[库参考]
以下是该Story实现可参考的库API文档。若与项目规约冲突，以规约为准。

{라이브러리명}

{库名称}

{context7에서 조회한 관련 API 문서 발췌}

{从context7查询到的相关API文档摘录}

{라이브러리명2}

{库名称2}

{context7에서 조회한 관련 API 문서 발췌}

(Library Reference는 1c에서 조회. 조회 결과가 없으면 [Library Reference] 섹션 전체를 생략한다)

undefined

{从context7查询到的相关API文档摘录}

（Library Reference在1c中查询。若无查询结果则省略整个[Library Reference]章节）

undefined

1c. Library Reference 조회

1c. 库参考查询

conventions.md 필터링 후, 각 Story에 전달할 라이브러리 레퍼런스를 준비한다.

라이브러리 추출:

Story의 Technical Notes에서 "주요 라이브러리" 항목을 확인한다.
라이브러리가 명시되어 있으면, Story당 최대 3개까지 context7로 조회한다.
라이브러리가 명시되어 있지 않으면 이 단계를 건너뛴다.

context7 조회 절차 (라이브러리당):

```
resolve-library-id
```
로 library ID를 확인한다.
```
query-docs
```
로 Story의 AC에 관련된 API 문서를 조회한다.
- query는 Story의 AC를 기반으로 구성한다 (예: "form validation with zod schema", "server actions with next.js app router")
- 범용적인 query보다 Story AC에 특화된 query가 효과적이다.
조회 결과에서 해당 Story AC에 직접 관련된 API/패턴만 추출한다 (전체 문서 전달 금지).

Fallback:

```
resolve-library-id
```
실패 (라이브러리 미발견): 해당 라이브러리는 건너뛴다.
```
query-docs
```
실패 또는 빈 결과: 해당 라이브러리는 건너뛴다.
context7 MCP 서버 연결 불가: 전체 단계를 건너뛰고 conventions만 전달한다.
모든 fallback은 정상 동작이다. Library Reference는 보충 자료이지 필수 전제조건이 아니다.

过滤conventions.md后，准备要传递给每个Story的库参考内容。

库提取：

检查Story的Technical Notes中的“主要库”条目。
若明确指定了库，则每个Story最多向context7查询3个库。
若未指定库，则跳过此步骤。

context7查询流程（每个库）：

通过
```
resolve-library-id
```
确认库ID。
通过
```
query-docs
```
查询与Story的AC相关的API文档：
- 查询语句基于Story的AC构建（例如："form validation with zod schema", "server actions with next.js app router"）
- 相较于通用查询，针对Story AC的特定查询更有效。
仅从查询结果中提取与该Story AC直接相关的API/模式（禁止传递完整文档）。

回退方案：

```
resolve-library-id
```
失败（未找到库）：跳过该库。
```
query-docs
```
失败或无结果：跳过该库。
无法连接到context7 MCP服务器：跳过整个步骤，仅传递规约内容。
所有回退均为正常操作。Library Reference是补充资料，非必需前置条件。

2. 모델 (orchestrate가 결정)

2. 模型（由orchestrate决定）

이 Lead의 모델은

bf-lead-orchestrate

가 스폰 시 지정한다:

에픽 내 L/XL Story 포함 시 Opus
S/M만이면 Sonnet

该Lead使用的模型由

bf-lead-orchestrate

生成时指定：

若Epic包含L/XL Story，则使用Opus
若仅包含S/M Story，则使用Sonnet

3. Story Agent 스폰

3. Story Agent生成

모든 난이도의 Story를 agent에게 위임한다. Lead는 코드를 직접 만지지 않는다.

将所有难度的Story委托给Agent处理。Lead不直接编写代码。

S/M Story → 단독 Agent (Sonnet)

S/M Story → 单个Agent（Sonnet）

Story당 1개의 Sonnet agent를 스폰한다.
```
.ralph-progress/{STORY-ID}.json
```
이 존재하면 초기 retry_count/approaches_count를 해당 파일에서 읽어 전달한다 (이전 중단 복구 시).
Agent에게 전달하는 정보:
- Story 문서 내용 (AC, Technical Notes)
- conventions 관련 섹션 (1b에서 필터링한 인라인 텍스트)
- library reference (1c에서 조회한 인라인 텍스트, 있으면)
- 수정 재실행인 경우: modification.md의 해당 Story 수정 지시 원문
- Ralph Loop 지침 (아래 "Story Agent용 Ralph Loop 지침" 참조)
- 기존 retry_count/approaches_count (있으면 — 이전 중단에서 복구된 값)
- "sprint-status.yaml을 수정하지 말 것"
- "
  "done"
  + commit hash + retry_count + approaches_count 또는
  "stuck"
  + stuck.md + retry_count + approaches_count로 보고할 것"

<HARD-GATE> Story agent는 sprint-status.yaml을 절대 읽거나 수정하지 않는다. 모든 상태 업데이트는 Lead가 "done"/"stuck" 신호를 수신한 후 수행한다. "상태만 빨리 기록하겠다"는 단일 쓰기 지점 원칙을 파괴하는 합리화이다. </HARD-GATE>

每个Story生成1个Sonnet Agent。
若
```
.ralph-progress/{STORY-ID}.json
```
存在，则从该文件读取初始retry_count/approaches_count并传递（用于恢复之前中断的任务）。
传递给Agent的信息：
- Story文档内容（AC、Technical Notes）
- 相关规约章节（1b中过滤后的内联文本）
- 库参考内容（1c中查询到的内联文本，若有）
- 若为修改重跑：modification.md中对应Story的修改指示原文
- Ralph Loop指南（参考下方“Story Agent用Ralph Loop指南”）
- 已有的retry_count/approaches_count（若有——从之前中断恢复的值）
- "请勿修改sprint-status.yaml"
- "请以
  "done"
  + commit hash + retry_count + approaches_count 或
  "stuck"
  + stuck.md + retry_count + approaches_count的形式报告"

<HARD-GATE> Story Agent绝对不能读取或修改sprint-status.yaml。所有状态更新均由Lead在收到"done"/"stuck"信号后执行。“先快速记录状态”的想法会破坏单一写入点原则，属于违规行为。 </HARD-GATE>

L Story → Sub-Lead (Opus) + Implementers (Sonnet)

L Story → Sub-Lead（Opus）+ 实现者（Sonnet）

Story당 1개의 Opus sub-lead를 스폰한다.
Sub-lead에게 전달하는 정보:
- Story 문서 내용
- conventions 관련 섹션 (1b에서 필터링한 인라인 텍스트)
- library reference (1c에서 조회한 인라인 텍스트, 있으면)
- 수정 지시 (있으면)
- "Sonnet implementer를 스폰하여 구현을 진행하라"
- "쟁점 해소 프로토콜에 따라 조율하라" (아래 참조)
- Ralph Loop 지침
- "sprint-status.yaml을 수정하지 말 것"
- "
  "done"
  + commit hash + retry_count + approaches_count 또는
  "stuck"
  + stuck.md + retry_count + approaches_count로 보고할 것"

每个Story生成1个Opus Sub-Lead。
传递给Sub-Lead的信息：
- Story文档内容
- 相关规约章节（1b中过滤后的内联文本）
- 库参考内容（1c中查询到的内联文本，若有）
- 修改指示（若有）
- "生成Sonnet实现者以推进开发"
- "按照争议解决协议进行协调"（参考下方）
- Ralph Loop指南
- "请勿修改sprint-status.yaml"
- "请以
  "done"
  + commit hash + retry_count + approaches_count 或
  "stuck"
  + stuck.md + retry_count + approaches_count的形式报告"

XL Story → Sub-Lead (Opus) + 3+ Teammates

XL Story → Sub-Lead（Opus）+ 3名以上团队成员

Story당 1개의 Opus sub-lead를 스폰한다.
Sub-lead에게 전달하는 정보:
- Story 문서 내용
- conventions 관련 섹션 (1b에서 필터링한 인라인 텍스트)
- library reference (1c에서 조회한 인라인 텍스트, 있으면)
- 수정 지시 (있으면)
- "3+ teammates를 스폰하여 구현, 통합, 리뷰 역할을 분담하라"
- "discourse로 설계 검증 후 구현을 진행하라"
- "쟁점 해소 프로토콜에 따라 조율하라"
- Ralph Loop 지침
- "sprint-status.yaml을 수정하지 말 것"
- "
  "done"
  + commit hash + retry_count + approaches_count 또는
  "stuck"
  + stuck.md + retry_count + approaches_count로 보고할 것"

每个Story生成1个Opus Sub-Lead。
传递给Sub-Lead的信息：
- Story文档内容
- 相关规约章节（1b中过滤后的内联文本）
- 库参考内容（1c中查询到的内联文本，若有）
- 修改指示（若有）
- "生成3名以上团队成员，分工负责实现、集成、评审"
- "通过discourse进行设计验证后再推进开发"
- "按照争议解决协议进行协调"
- Ralph Loop指南
- "请勿修改sprint-status.yaml"
- "请以
  "done"
  + commit hash + retry_count + approaches_count 或
  "stuck"
  + stuck.md + retry_count + approaches_count的形式报告"

4. 병렬 실행 규칙

4. 并行执行规则

디폴트는 병렬이다. Story 문서의 Technical Notes에서 변경 대상 파일을 확인하고, 아래 순차 조건에 해당하지 않으면 하나의 응답에서 여러 Task tool call을 동시에 보내 병렬 스폰한다.

순차 실행 조건 (이 조건에 해당할 때만 순차):

파일 겹침: 두 Story의 Target files에 동일 파일이 존재
Dependencies 명시: Story 문서에 다른 Story에 대한 의존성이 명시됨
공유 파일 충돌: 아래 파일을 변경하는 Story는 "겹침"으로 간주
- Lock 파일:
```
package-lock.json
```
  ,
```
yarn.lock
```
  ,
```
pnpm-lock.yaml
```
  ,
```
Gemfile.lock
```
  ,
```
poetry.lock
```
  ,
```
go.sum
```
- 공유 설정:
```
tsconfig.json
```
  ,
```
webpack.config.*
```
  ,
```
vite.config.*
```
  ,
```
.env.*
```
- 자동 생성 파일:
```
schema.prisma
```
  →
```
@prisma/client
```
  , DB migration 파일
Story agent가 lock 파일을 변경해야 하는 경우 (새 의존성 설치 등): 해당 Story를 병렬 그룹에서 분리하여 단독 또는 순차 실행

默认并行执行。检查Story文档的Technical Notes中的目标修改文件，若不符合以下顺序执行条件，则在一个响应中同时调用多个Task工具，并行生成Agent。

顺序执行条件（仅符合以下条件时才顺序执行）：

文件重叠：两个Story的Target files中存在相同文件
明确依赖：Story文档中明确指定了对其他Story的依赖

共享文件冲突：修改以下文件的Story视为“重叠”

Lock文件：

package-lock.json

yarn.lock

pnpm-lock.yaml

Gemfile.lock

poetry.lock

go.sum

共享配置：

tsconfig.json

webpack.config.*

vite.config.*

.env.*

自动生成文件：
```
schema.prisma
```
→
```
@prisma/client
```
, DB迁移文件

Story Agent需要修改Lock文件时（如安装新依赖）：将该Story从并行组中分离，单独或顺序执行

5. 모니터링 루프

5. 监控循环

sprint-status.yaml 갱신은 CLAUDE.md의 Read-yq-Verify 프로토콜을 따른다.

각 Story agent로부터 완료 신호를 수신한다:

"done" + commit hash 수신 시:

sprint-status.yaml 업데이트 (Lead가 직접,

yq -i

명령어 사용):

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.status = "done" |
  .<TICKET>.<EPIC>.<STORY>.tdd = "done" |
  .<TICKET>.<EPIC>.<STORY>.model_used = "sonnet" |
  .<TICKET>.<EPIC>.<STORY>.ralph_retries = 1 |
  .<TICKET>.<EPIC>.<STORY>.ralph_approaches = 0 |
  .<TICKET>.<EPIC>.<STORY>.ralph_stuck = false
' docs/sprint-status.yaml

model_used

: 실제 사용된 모델 전략 (

"sonnet"

"opus-lead"

"opus-lead+3"

)

```
ralph_retries
```
: agent가 보고한 재시도 횟수
```
ralph_approaches
```
: agent가 보고한 접근 전환 횟수

"stuck" + stuck.md 수신 시:

sprint-status.yaml 업데이트:

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.ralph_stuck = true |
  .<TICKET>.<EPIC>.<STORY>.ralph_retries = 3 |
  .<TICKET>.<EPIC>.<STORY>.ralph_approaches = 2
' docs/sprint-status.yaml

stuck.md를
```
docs/reviews/{STORY-ID}-stuck.md
```
에 저장한다.
git commit하지 않는다 — docs/ 산출물은 Phase 4 Archive에서 일괄 커밋한다.
다른 Story들은 계속 진행한다 (stuck Story가 있어도 나머지를 중단하지 않음).
stuck Story의
status
는 변경하지 않는다 — orchestrate가 자동 판단 시
```
skipped
```
로 변경한다.

모든 Story가 완료(done 또는 stuck)될 때까지 대기한다.

更新sprint-status.yaml需遵循CLAUDE.md中的Read-yq-Verify协议。

接收每个Story Agent的完成信号：

收到"done" + commit hash时：

更新sprint-status.yaml（由Lead直接执行，使用

yq -i

命令）：

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.status = "done" |
  .<TICKET>.<EPIC>.<STORY>.tdd = "done" |
  .<TICKET>.<EPIC>.<STORY>.model_used = "sonnet" |
  .<TICKET>.<EPIC>.<STORY>.ralph_retries = 1 |
  .<TICKET>.<EPIC>.<STORY>.ralph_approaches = 0 |
  .<TICKET>.<EPIC>.<STORY>.ralph_stuck = false
' docs/sprint-status.yaml

model_used

: 实际使用的模型策略（

"sonnet"

"opus-lead"

"opus-lead+3"

）

```
ralph_retries
```
: Agent报告的重试次数
```
ralph_approaches
```
: Agent报告的方法切换次数

收到"stuck" + stuck.md时：

更新sprint-status.yaml：

bash

yq -i '
  .<TICKET>.<EPIC>.<STORY>.ralph_stuck = true |
  .<TICKET>.<EPIC>.<STORY>.ralph_retries = 3 |
  .<TICKET>.<EPIC>.<STORY>.ralph_approaches = 2
' docs/sprint-status.yaml

将stuck.md保存到
```
docs/reviews/{STORY-ID}-stuck.md
```
。
不执行git commit —— docs/下的产物将在Phase 4 Archive中统一提交。
继续处理其他Story（即使存在stuck Story，也不中断其余任务）。
不修改stuck Story的
status
—— 由orchestrate自动判断并标记为
```
skipped
```
。

等待所有Story完成（done或stuck）。

6. Done 신호

6. Done信号

모든 Story 완료 후 orchestrate에 보고한다:

stuck Story 없음:

```
"done"
```
+ sprint-status.yaml 경로

stuck Story 있음:

```
"done (stuck: {STORY-ID}, {STORY-ID})"
```
+ sprint-status.yaml 경로 + stuck.md 경로들

종료 (컨텍스트 소멸).

所有Story完成后，向orchestrate报告：

无stuck Story：

```
"done"
```
+ sprint-status.yaml路径

存在stuck Story：

```
"done (stuck: {STORY-ID}, {STORY-ID})"
```
+ sprint-status.yaml路径 + stuck.md路径列表

退出（上下文销毁）。

Story Agent용 Ralph Loop 지침

Story Agent用Ralph Loop指南

Story agent에게 전달할 TDD 지침이다. Agent는 이 지침을 그대로 따른다.

这是传递给Story Agent的TDD指南。Agent需严格遵循。

TDD 사이클

TDD循环

<HARD-GATE> 구현 코드를 작성하기 전에 반드시 테스트를 먼저 작성하고 Red(실패)를 확인해야 한다. 테스트와 구현을 동시에 작성하는 것은 TDD 위반이다. "간단하니까 같이 작성해도 된다"는 이 게이트를 우회하는 전형적인 합리화이다. </HARD-GATE>

단위 테스트 작성 (AC 기반)
Red 확인: 테스트 실행 → 실패 확인
- 예상대로 실패하지 않으면 테스트 코드 수정
구현
Green 확인: 테스트 재실행 → 통과 확인
- 실패하면 아래 가드레일에 따라 재시도
리팩토링 (필요 시, Green 유지 확인)
git commit:
```
[{TICKET}] {간단한 설명}
```
- docs/
  하위 파일은 커밋에 포함하지 않는다 (sprint-status.yaml, story 문서 등 모두 제외)
Lead에 done 보고:
```
"done"
```
+ commit hash +
```
retry_count
```
+
```
approaches_count
```

<HARD-GATE> 编写实现代码前，必须先编写测试并确认Red（失败）状态。同时编写测试和实现属于TDD违规行为。“因为简单所以可以一起写”是典型的绕开该规则的借口。 </HARD-GATE>

编写单元测试（基于AC）
确认Red状态：运行测试 → 确认失败
- 若未按预期失败，则修改测试代码
实现功能
确认Green状态：重新运行测试 → 确认通过
- 若失败，则按照以下防护指南重试
重构（若需要，需保持Green状态）
git提交：
```
[{TICKET}] {简短描述}
```
- 提交时不包含
  docs/
  下的文件（sprint-status.yaml、Story文档等均需排除）
向Lead报告done：
```
"done"
```
+ commit hash +
```
retry_count
```
+
```
approaches_count
```

Ralph Loop 가드레일

Ralph Loop防护指南

a) 최대 재시도 횟수: 5회

Green 검증 실패 → 구현 수정 → 재실행을 최대 5회까지 반복한다.
```
retry_count
```
를 0부터 시작하여 매 실패마다 1 증가.

b) 반복 실패 감지 (Stuck Detection)

매 실패 시 에러 메시지의 핵심 내용(에러 타입 + 발생 파일)을 기록한다.
직전 시도와 동일한 근본 원인의 에러가 연속 2회 발생하면, 접근 방식을 전환한다:
1. 테스트 코드의 기대값이 잘못되었는지 재검토
2. AC 해석이 올바른지 Story 파일 재확인
3. 구현 전략을 근본적으로 변경 (다른 알고리즘/패턴 적용)
```
approaches_count
```
를 0부터 시작하여 전환 시마다 1 증가.

c) 진행 상태 파일 기록 (크래시 복구용)

매 재시도 후

.ralph-progress/{STORY-ID}.json

에 현재 상태를 기록한다:

json

{
  "retry_count": 2,
  "approaches_count": 1,
  "last_error_type": "TypeError",
  "last_error_file": "src/auth/login.ts"
}

이 파일은 에이전트 크래시 후 bf-resume이 재개할 때 Ralph Loop 카운트를 복원하는 데 사용된다.
Story 완료("done") 또는 stuck 보고 후 해당 파일을 삭제한다.
sprint-status.yaml은 여전히 수정하지 않는다 — 이 파일은 ralph-progress 전용이다.

d) 한도 초과 시 → "stuck" 보고

```
retry_count >= 5
```
에 도달하면 루프를 즉시 중단한다.
stuck.md를 작성한다:

markdown

undefined

a) 最大重试次数：5次

Green验证失败 → 修改实现 → 重新执行，最多重复5次。
```
retry_count
```
从0开始，每次失败递增1。

b) 重复失败检测（Stuck检测）

每次失败时记录错误信息的核心内容（错误类型 + 发生文件）。
若连续2次出现相同根本原因的错误，则切换实现方法：
1. 重新检查测试代码的预期值是否正确
2. 重新确认Story文件中的AC理解是否正确
3. 彻底改变实现策略（应用不同算法/模式）
```
approaches_count
```
从0开始，每次切换方法递增1。

c) 记录进度文件（用于崩溃恢复）

每次重试后，将当前状态记录到

.ralph-progress/{STORY-ID}.json

：

json

{
  "retry_count": 2,
  "approaches_count": 1,
  "last_error_type": "TypeError",
  "last_error_file": "src/auth/login.ts"
}

该文件用于在Agent崩溃后，由bf-resume恢复Ralph Loop计数。
报告Story完成（"done"）或stuck后，删除该文件。
仍不得修改sprint-status.yaml —— 该文件仅用于ralph-progress。

d) 超过限制时 → 报告"stuck"

当
```
retry_count >=5
```
时，立即终止循环。
编写stuck.md：

markdown

undefined

Stuck 보고서: {STORY-ID}

Stuck报告：{STORY-ID}

재시도 횟수: {retry_count}/5

重试次数：{retry_count}/5

접근 전환 횟수: {approaches_count}

方法切换次数：{approaches_count}

시도한 접근 방식

尝试过的方法

{접근 1} — {에러 요약}
{접근 2} — {에러 요약}

{方法1} — {错误摘要}
{方法2} — {错误摘要}

마지막 에러

最后一次错误

{전체 에러 출력}

{完整错误输出}

변경된 파일

修改的文件

{변경 파일 목록}


- `.ralph-progress/{STORY-ID}.json` 삭제
- Lead에 보고: `"stuck"` + stuck.md 경로
- `retry_count`, `approaches_count`를 함께 보고한다.

{修改文件列表}


- 删除`.ralph-progress/{STORY-ID}.json`
- 向Lead报告：`"stuck"` + stuck.md路径
- 同时报告`retry_count`和`approaches_count`。

쟁점 해소 프로토콜 (L/XL Story의 Sub-Lead/Teammates에 적용)

争议解决协议（适用于L/XL Story的Sub-Lead/团队成员）

Teammates 직접 대화:
```
SendMessage
```
로 직접 challenge/agree/보완
- 합의됨 → Sub-Lead에 결론만 보고
미합의 시 Sub-Lead 중재: 프로젝트 방향성(conventions.md) 기준으로 판단
- Sub-Lead 결정으로 확정
그래도 미합의 → 버린다 (기록): 더 이상 토큰을 쓰지 않음

团队成员直接沟通：通过
```
SendMessage
```
直接提出质疑/同意/补充
- 达成一致 → 仅向Sub-Lead报告结论
未达成一致时由Sub-Lead调解：以项目方向（conventions.md）为标准判断
- 以Sub-Lead的决定为准
仍未达成一致 → 放弃（记录）：不再消耗令牌

Agent Teams 실패 시 Fallback (L/XL)

Agent团队失败时的回退方案（L/XL）

Task tool 에러 (agent 생성 실패): 단독 Sonnet agent로 fallback (S/M과 동일 방식)
Teammate 10분 이상 무응답: 해당 teammate 제외하고 나머지로 진행
프로세스 비정상 종료: 단독 Sonnet agent로 fallback

Task工具错误（Agent创建失败）：回退为使用单个Sonnet Agent（与S/M处理方式相同）
团队成员10分钟以上无响应：排除该成员，继续使用其余成员推进
进程异常终止：回退为使用单个Sonnet Agent

Output Format

输出格式

sprint-status.yaml 업데이트 (이 Lead가 구현 단계의 유일한 쓰기 지점)
```
"done"
```
또는
```
"done (stuck)"
```
신호를 orchestrate에 전달

更新sprint-status.yaml（该Lead是实现阶段唯一的写入点）
向orchestrate传递
```
"done"
```
或
```
"done (stuck)"
```
信号