bf-lead-review

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Lead Review (Discourse Pattern)

Lead评审（Discourse模式）

Overview

概述

Discourse 조율 패턴으로 다관점 리뷰를 수행하는 Lead 스킬이다. 두 가지 모드를 지원한다:

tech-spec 모드: Tech Spec 문서를 리뷰하고 사람 개입 ①을 위한 결과를 생성한다.
epic-review 모드: 에픽 전체 구현을 통합 리뷰하고, 자기 완결적 review.md를 생성한 뒤 종료한다. 사람과 직접 소통하지 않는다.

这是一项采用Discourse协调模式开展多视角评审的Lead技能。支持两种模式：

tech-spec模式：评审Tech Spec文档，生成需人工介入①的结果。
epic-review模式：对史诗级功能的完整实现进行集成评审，生成自包含的review.md后终止，无需与人工直接交互。

When to Use

使用场景

tech-spec 모드:
```
/bf-spec
```
이 Tech Spec 작성 후 자동 스폰
epic-review 모드:
```
bf-lead-orchestrate
```
가 E2E 통과 후 자동 스폰
직접 호출하지 않는다.

tech-spec模式：
```
/bf-spec
```
在Tech Spec编写完成后自动触发
epic-review模式：
```
bf-lead-orchestrate
```
在E2E测试通过后自动触发
请勿直接调用。

Prerequisites

前置条件

tech-spec 모드:
```
docs/tech-specs/{TICKET}-tech-spec.md
```
존재
epic-review 모드: 해당 에픽의 모든 Story
```
status: done
```
또는
```
skipped
```
, E2E
```
passed
```
또는
```
skipped
```
또는
```
escalated
```
또는
```
max-regression-cycles
```

tech-spec模式：存在
```
docs/tech-specs/{TICKET}-tech-spec.md
```
文件
epic-review模式：该史诗的所有Story状态为
```
done
```
或
```
skipped
```
，E2E测试状态为
```
passed
```
或
```
skipped
```
或
```
escalated
```
或
```
max-regression-cycles
```

Error Handling

错误处理

tech-spec 파일 미존재:
```
"error: tech-spec not found"
```
신호를 스폰한 상위 에이전트에 전달 후 종료
conventions.md 미존재 (epic-review 모드): Convention Guard를 "conventions.md가 없으므로 일반 코드 품질 기준으로 검사" 모드로 실행. 결과에 "conventions.md 미존재로 기본 규칙 적용" 명시
git diff 추출 실패: 에픽 첫 Story 커밋을 찾을 수 없으면
```
HEAD~{story_count}..HEAD
```
범위로 fallback. 그래도 실패 시
```
"error: diff extraction failed"
```
보고

Tech Spec文件不存在：向上级触发的Agent发送
```
"error: tech-spec not found"
```
信号后终止
conventions.md不存在（epic-review模式）：将Convention Guard切换为“因无conventions.md，按通用代码质量标准检查”模式运行。结果中需注明“因不存在conventions.md，采用默认规则”
git diff提取失败：若无法找到史诗首个Story的提交，则回退至
```
HEAD~{story_count}..HEAD
```
范围。若仍失败，则上报
```
"error: diff extraction failed"
```

Instructions

操作步骤

1. 모드 감지

1. 模式识别

스폰 시 전달받은 파라미터로 모드를 결정한다:

```
mode: "tech-spec"
```
+ tech-spec 경로
```
mode: "epic-review"
```
+ epic ID + tech-spec 경로

根据触发时传入的参数确定模式：

```
mode: "tech-spec"
```
+ Tech Spec路径
```
mode: "epic-review"
```
+ 史诗ID + Tech Spec路径

2. 초기 로딩

2. 初始加载

yq 전제조건 체크 (최초 1회, epic-review 모드):

bash

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

모드	읽는 파일
tech-spec	tech-spec.md, conventions.md
epic-review	tech-spec.md, conventions.md, 에픽 전체 git diff ( `git log --oneline --grep="({STORY-ID-1}\|{STORY-ID-2}...)" --reverse` 로 에픽 첫 Story 커밋을 찾고, 그 부모 커밋 ~ HEAD를 diff 범위로 사용)

yq前置条件检查（仅首次执行，epic-review模式）：

bash

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

模式	读取文件
tech-spec	tech-spec.md, conventions.md
epic-review	tech-spec.md, conventions.md, 史诗完整git diff（通过 `git log --oneline --grep="({STORY-ID-1}\|{STORY-ID-2}...)" --reverse` 找到史诗首个Story的提交，以其父提交~HEAD作为diff范围）

3. 모델 선택

3. 模型选择

모드	모델
tech-spec	항상 Opus (프로젝트 전체 의사결정)
epic-review	에픽 내 L/XL Story 포함 시 Opus, S/M만이면 Sonnet

模式	模型
tech-spec	始终使用Opus（用于项目整体决策）
epic-review	若史诗包含L/XL级Story则使用Opus，仅包含S/M级则使用Sonnet

4. 리뷰어 팀 구성

4. 评审团队组建

tech-spec 모드:

Lead가 Tech Spec을 읽고 프로젝트 특성에 맞는 3가지 리뷰 페르소나를 추천한다.
- 예: Architecture Reviewer, Security Reviewer, Performance Reviewer
- 또는: Backend Engineer, Frontend Engineer, QA Engineer
추천된 페르소나 3명을 teammate로 생성한다 (
```
model: opus
```
).

epic-review 모드:

<HARD-GATE> Convention Guard 리뷰어는 epic-review에서 절대 생략할 수 없다. conventions.md가 비어있거나 짧아도 Convention Guard를 포함해야 한다. "컨벤션이 아직 없으니 생략해도 된다"는 이 게이트를 우회하는 전형적인 합리화이다. </HARD-GATE>

Lead가 에픽 변경 범위를 분석하여 2~3명의 리뷰어를 구성한다:
- Convention Guard (필수):
```
docs/conventions.md
```
  기준 컨벤션 준수 여부
- 추가 1~2명: 프로젝트 특성에 따라 Architecture, Security, Performance 중 선택
모델은 3단계에서 결정한 모델과 동일하게 적용한다.

tech-spec模式：

Lead读取Tech Spec后，根据项目特性推荐3种评审角色。
- 示例：架构评审员、安全评审员、性能评审员
- 或：后端工程师、前端工程师、QA工程师
创建3个对应推荐角色的teammate（
```
model: opus
```
）。

epic-review模式：

<HARD-GATE> Convention Guard评审员在epic-review中绝对不可省略。即使conventions.md为空或内容简短，也必须包含Convention Guard。“因尚无规范可省略”属于典型的绕开该关卡的合理化借口。 </HARD-GATE>

Lead分析史诗的变更范围，组建2~3名评审员：
- Convention Guard（必填）：依据
```
docs/conventions.md
```
  检查规范合规性
- 额外1~2名：根据项目特性从架构、安全、性能领域选择
模型采用第3步确定的模型。

5. 독립 분석

5. 独立分析

<HARD-GATE> 모든 리뷰어의 독립 분석이 완료될 때까지 discourse(교차 검증)를 시작하지 않는다. 독립 분석 없이 바로 토론에 들어가면 첫 번째 의견에 앵커링되어 다관점 리뷰의 가치가 사라진다. </HARD-GATE>

각 리뷰어가 독립적으로 분석을 수행한다:

tech-spec 모드 관점:

아키텍처 정합성: 기존 패턴과의 일관성, 모듈 경계 위반
보안: 인증/인가, 데이터 노출, 입력 검증
성능: 쿼리 최적화, 캐싱 전략
테스트 가능성: AC가 테스트 가능한 형태인지, 엣지 케이스 누락
변경 영향도: 사이드이펙트, 하위 호환성

epic-review 모드 관점:

Convention Guard:
```
docs/conventions.md
```
기준 준수 여부
스토리 간 중복/불일치: 중복 유틸 함수, 네이밍 불일치
아키텍처 드리프트: 개별로는 맞지만 합치면 드러나는 구조 문제
테스트 커버리지: AC 대비 테스트 누락
보안: 인젝션, 인증 우회, 데이터 노출

<HARD-GATE> 必须等待所有评审员完成独立分析后，方可启动discourse（交叉验证）。若无独立分析直接进入讨论，会导致首条意见锚定，丧失多视角评审的价值。 </HARD-GATE>

各评审员独立开展分析：

tech-spec模式评审视角：

架构一致性：与现有模式的一致性、模块边界违规情况
安全：认证/授权、数据泄露、输入验证
性能：查询优化、缓存策略
可测试性：验收标准是否具备可测试性、是否遗漏边缘用例
变更影响范围：副作用、向下兼容性

epic-review模式评审视角：

Convention Guard：依据
```
docs/conventions.md
```
检查合规性
Story间重复/不一致：重复工具函数、命名不一致
架构漂移：单独看没问题但整合后暴露的结构问题
测试覆盖率：与验收标准相比的测试遗漏情况
安全：注入攻击、认证绕过、数据泄露

6. Discourse (교차 검증) — 쟁점 해소 프로토콜

6. Discourse（交叉验证）——争议解决协议

다음 우선순위로 쟁점을 해소한다:

① 리뷰어 직접 대화:

Lead가 각 리뷰어의 발견사항을 수집하여 공유한다.
리뷰어끼리
```
SendMessage
```
로 직접 challenge/agree/보완한다.
합의되면 → Lead에 결론만 보고.

② 미합의 시 Lead 중재:

Lead가 프로젝트 방향성(tech-spec, conventions)을 기준으로 판단한다.
Lead 결정으로 확정.

③ 그래도 미합의 → 버린다 (기록):

최종 결과에 "미합의 쟁점"으로 포함한다.
더 이상 토큰을 쓰지 않는다.

按以下优先级解决争议：

① 评审员直接对话：

Lead收集并共享各评审员的发现。
评审员通过
```
SendMessage
```
直接提出质疑/达成共识/补充内容。
达成共识后→仅向Lead上报结论。

② 未达成共识时由Lead调解：

Lead依据项目方向（tech-spec、conventions）做出判断。
以Lead的决定为准。

③ 仍未达成共识→记录后搁置：

在最终结果中以“未达成共识的争议”列出。
不再消耗额外令牌。

7. 리뷰 결과 통합

7. 评审结果整合

발견사항을 분류한다:

🔴 Blocker (반드시 수정)
🟡 Recommended (권장 수정)
🟢 Confirmed (확인 완료)
미합의 쟁점 (쟁점 + 각 리뷰어 의견 + Lead 최종 판단 + 근거)

对发现的问题进行分类：

🔴 Blocker（必须修改）
🟡 Recommended（建议修改）
🟢 Confirmed（已确认无误）
未达成共识的争议（争议内容+各评审员意见+Lead最终判断+依据）

8. 모드별 출력 및 후속 처리

8. 分模式输出及后续处理

tech-spec 모드:

tech-spec模式：

```
docs/reviews/{TICKET}-tech-spec-review.md
```
에 저장한다.
- ```
docs/reviews/
```
  디렉토리가 없으면 생성
- 재리뷰 시에는
```
## Re-review ({날짜})
```
  섹션을 append
git commit하지 않는다 — docs/ 산출물은 Phase 4 Archive에서 일괄 커밋한다.
스폰한 상위 에이전트에 전달:
- ```
"done"
```
  + review.md 경로
종료 (컨텍스트 소멸).

保存至

docs/reviews/{TICKET}-tech-spec-review.md

。

若
```
docs/reviews/
```
目录不存在则创建
重新评审时追加
```
## 重新评审（{日期}）
```
章节

不执行git commit——docs/产出物在Phase 4 Archive中统一提交。
向上级触发的Agent传递：
- ```
"done"
```
  + review.md路径
终止（上下文销毁）。

epic-review 모드:

epic-review模式：

```
docs/reviews/{EPIC-ID}-review.md
```
에 저장한다.
- 수정 재실행(modification)으로 재리뷰하는 경우: 기존 파일을 덮어쓴다 (이전 리뷰는 git 이력에 보존됨). sprint-status.yaml의 모든 done Story의
```
review_blockers
```
  /
```
review_recommended
```
  도 새로 계산하여 덮어쓴다.
sprint-status.yaml 업데이트 (CLAUDE.md의 Read-yq-Verify 프로토콜,
```
yq -i
```
명령어 사용):
- 에픽 내 각 Story의
```
review_blockers
```
  ,
```
review_recommended
```
  건수 기록
- cross-story 귀속 규칙: 여러 Story에 걸친 발견 사항(네이밍 불일치, 중복 유틸 등)은 가장 관련 높은 Story에 귀속한다. 특정 Story에 귀속할 수 없는 경우 에픽의 첫 번째 done Story에 귀속한다. 모든 Story가 skipped인 에픽에서는 review_blockers/review_recommended를 sprint-status.yaml에 기록하지 않는다 (귀속 대상 없음, review.md에만 기록).
bash
```
yq -i '
  .<TICKET>.<EPIC>.<STORY>.review_blockers = 2 |
  .<TICKET>.<EPIC>.<STORY>.review_recommended = 5
' docs/sprint-status.yaml
```
git commit하지 않는다 — docs/ 산출물은 Phase 4 Archive에서 일괄 커밋한다.
Blocker 판정 및 종료:
- Blocker 0건: 에픽 내 모든
```
status: done
```
  Story의
```
review: approved
```
  로 업데이트 (
```
status: skipped
```
  Story는 bf-execute/bf-resume이 사람 "진행" 선택 시 처리):
  bash
```
yq -i '.<TICKET>.<EPIC>.<STORY>.review = "approved"' docs/sprint-status.yaml
```
  스폰한 상위 에이전트에 전달:
```
"done: approved"
```
  + review.md 경로
- Blocker 1건 이상: review 상태를 유지 (
```
pending
```
  ) 스폰한 상위 에이전트에 전달:
```
"done: blockers"
```
  + review.md 경로
종료 (컨텍스트 소멸).

保存至
```
docs/reviews/{EPIC-ID}-review.md
```
。
- 因修改重新执行评审时：覆盖原有文件（历史评审记录保留在git历史中）。同时重新计算sprint-status.yaml中所有done状态Story的
```
review_blockers
```
  /
```
review_recommended
```
  并覆盖。
更新sprint-status.yaml（遵循CLAUDE.md的Read-yq-Verify协议，使用
```
yq -i
```
命令）：
- 记录史诗内各Story的
```
review_blockers
```
  、
```
review_recommended
```
  数量
- 跨Story归属规则：涉及多个Story的发现（命名不一致、重复工具函数等）归属最相关的Story。若无法归属至特定Story，则归属史诗的首个done状态Story。所有Story均为skipped状态的史诗，不在sprint-status.yaml中记录review_blockers/review_recommended（无归属对象，仅在review.md中记录）。
bash
```
yq -i '
  .<TICKET>.<EPIC>.<STORY>.review_blockers = 2 |
  .<TICKET>.<EPIC>.<STORY>.review_recommended = 5
' docs/sprint-status.yaml
```
不执行git commit——docs/产出物在Phase 4 Archive中统一提交。
Blocker判定及终止：
- Blocker为0项：将史诗内所有
```
status: done
```
  的Story的
```
review
```
  更新为
```
approved
```
  （
```
status: skipped
```
  的Story由bf-execute/bf-resume在人工选择“推进”时处理）：
  bash
```
yq -i '.<TICKET>.<EPIC>.<STORY>.review = "approved"' docs/sprint-status.yaml
```
  向上级触发的Agent传递：
```
"done: approved"
```
  + review.md路径
- Blocker≥1项：保持review状态为
```
pending
```
  向上级触发的Agent传递：
```
"done: blockers"
```
  + review.md路径
终止（上下文销毁）。

Output Format

输出格式

review.md 구조

review.md结构

markdown

undefined

markdown

undefined

{TICKET 또는 EPIC-ID} 리뷰

{TICKET或EPIC-ID}评审

리뷰 개요

评审概述

모드: {tech-spec | epic-review}
리뷰어: {페르소나 목록}
날짜: {YYYY-MM-DD}

模式：{tech-spec | epic-review}
评审员：{角色列表}
日期：{YYYY-MM-DD}

🔴 Blocker (N건)

🔴 Blocker（N项）

[{위치}] 설명 + 수정 방안

[{位置}] 说明 + 修改方案

🟡 Recommended (N건)

🟡 Recommended（N项）

[{위치}] 설명 + 권장 수정

[{位置}] 说明 + 建议修改内容

🟢 Confirmed (N건)

🟢 Confirmed（N项）

확인 완료 항목 요약

已确认无误的内容摘要

미합의 쟁점

未达成共识的争议

쟁점	입장 A	입장 B	Lead 최종 판단	근거
...	...	...	...	...

争议	立场A	立场B	Lead最终判断	依据
...	...	...	...	...

권장 조치 (epic-review 모드만)

建议措施（仅epic-review模式）

Blocker (즉시 수정 필요)

Blocker（需立即修改）

{STORY-ID}: {구체적 수정 내용 + 파일:라인 위치}

{STORY-ID}：{具体修改内容 + 文件:行号位置}

Recommended (권장)

Recommended（建议修改）

{항목}

undefined

{事项}

undefined

Fallback

降级方案

Agent Teams 생성 실패 시: 메인 세션(또는 스폰한 상위 에이전트)에서 단일 Opus로 리뷰 수행
Teammate 무응답 (10분 이상): 해당 역할을 제외하고 나머지 결과로 진행, 제외된 역할을 결과에 명시

若Agent Teams创建失败：在主会话（或上级触发的Agent）中使用单个Opus完成评审
若Teammate无响应（超过10分钟）：排除该角色，基于剩余评审结果继续推进，并在结果中注明排除的角色