bf-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

BF Spec (Entry Point)

Overview

概述

BF 워크플로우의 진입점이다. 기획자가 제공한 AC 문서를 기반으로 Tech Spec을 작성하고, 자동으로

bf-lead-review

를 스폰하여 다관점 리뷰를 수행한다. 리뷰 결과를 사람에게 제시하여 승인 여부를 판단하게 한다 (사람 개입 ①).

这是BF工作流的入口。基于策划者提供的AC文档撰写Tech Spec，并自动发起

bf-lead-review

以开展多视角评审。将评审结果呈现给相关人员，由其判断是否批准（人工介入点①）。

When to Use

使用场景

사용자가
```
/bf-spec
```
을 입력했을 때
새로운 기능 개발 또는 변경 요청이 있을 때

当用户输入
```
/bf-spec
```
时
有新功能开发或变更请求时

Prerequisites

前置条件

워크플로우 진입점이므로 별도 전제조건 없음
사용자가 AC 문서 또는 변경 요청 내용을 준비한 상태여야 함

作为工作流入口，无额外前置条件
用户需准备好AC文档或变更请求内容

Error Handling

错误处理

AC 문서가 제공되지 않으면: "AC 문서 또는 변경 요청 내용을 제공해 주세요." 안내
Jira 티켓 번호 미제공 시: "Jira 티켓 번호를 알려주세요. 없으면 임시 ID를 생성합니다." 안내 후
```
BF-{YYYYMMDD}-{N}
```
형식으로 자동 생성
bf-lead-review 스폰 실패 시: 메인 세션에서 단일 Opus로 리뷰를 직접 수행하고, 사용자에게 "Agent Teams 구성에 실패하여 단독으로 리뷰합니다."를 알림

未提供AC文档时："AC 문서 또는 변경 요청 내용을 제공해 주세요." 翻译为："请提供AC文档或变更请求内容。"
Jira 티켓 번호 미제공 시："Jira 티켓 번호를 알려주세요. 없으면 임시 ID를 생성합니다." 翻译为："请告知Jira工单编号。若无编号，将生成临时ID。"，随后自动生成
```
BF-{YYYYMMDD}-{N}
```
格式的ID
bf-lead-review 스폰 실패 시："Agent Teams 구성에 실패하여 단독으로 리뷰합니다." 翻译为："Agent Teams配置失败，将单独进行评审。"

Instructions

操作步骤

1. 입력 수집

1. 收集输入

사용자에게 다음 입력을 요청한다:

AC 문서 또는 내용
관련 Jira 티켓 번호

向用户请求以下输入：

AC文档或内容
相关Jira工单编号

2. 코드베이스 분석 및 초기 conventions.md 생성

2. 代码库分析及初始conventions.md生成

기존 코드베이스를 분석한다:

변경 대상 모듈/파일 식별
기존 아키텍처 패턴 확인
의존성 그래프 파악

conventions.md 초기 생성 (

docs/conventions.md

가 없는 경우):

코드베이스 분석 결과를 기반으로 초기 conventions.md를 생성한다:

markdown

# 프로젝트 컨벤션

## 아키텍처
- {프레임워크}: {발견된 아키텍처 패턴 — 예: Layered, Hexagonal}
- 모듈 구조: {발견된 디렉토리/모듈 규칙}

## 네이밍
- 파일명: {발견된 패턴 — 예: kebab-case, PascalCase}
- 함수/변수: {발견된 패턴}

## 테스트
- 테스트 프레임워크: {발견된 도구}
- 테스트 파일 위치: {규칙}

## 코드 스타일
- {발견된 주요 코드 스타일 규칙}

{아래 concern-area 섹션은 코드베이스에서 해당 기술 스택이 감지된 경우에만 포함}

## UI 패턴
- {React/Vue/Angular 등 감지 시: 컴포넌트 구조, 상태 관리 패턴}

## API 패턴
- {Express/Fastify/NestJS/Django 등 감지 시: 엔드포인트 설계, 에러 핸들링 패턴}

## DB 패턴
- {Prisma/TypeORM/Drizzle 등 감지 시: 스키마 규칙, 마이그레이션 패턴}

concern-area 섹션(UI Patterns, API Patterns, Database Patterns, Security Patterns, Infrastructure Patterns)은 코드베이스에서 해당 기술 스택이 감지된 경우에만 포함한다. 감지되지 않은 기술 스택의 섹션은 생성하지 않는다. 초기 seed이므로 핵심 패턴만 간결하게 기재하고, 이후
```
/bf-update-conventions
```
가 축적한다.
이미 존재하면 건너뛴다.

分析现有代码库：

识别需变更的模块/文件
确认现有架构模式
梳理依赖关系图

初始生成conventions.md（当

docs/conventions.md

不存在时）：

基于代码库分析结果生成初始conventions.md：

markdown

# 项目约定

## 架构
- {프레임워크}: {발견된 아키텍처 패턴 — 예: Layered, Hexagonal} 翻译为：- {框架}: {发现的架构模式 — 示例：分层架构、六边形架构}
- 모듈 구조: {발견된 디렉토리/모듈 규칙} 翻译为：- 模块结构: {发现的目录/模块规则}

## 命名规范
- 파일명: {발견된 패턴 — 예: kebab-case, PascalCase} 翻译为：- 文件名: {发现的模式 — 示例：kebab-case、PascalCase}
- 함수/변수: {발견된 패턴} 翻译为：- 函数/变量: {发现的模式}

## 测试
- 테스트 프레임워크: {발견된 도구} 翻译为：- 测试框架: {发现的工具}
- 테스트 파일 위치: {규칙} 翻译为：- 测试文件位置: {规则}

## 代码风格
- {발견된 주요 코드 스타일 규칙} 翻译为：- {发现的主要代码风格规则}

{아래 concern-area 섹션은 코드베이스에서 해당 기술 스택이 감지된 경우에만 포함} 翻译为：{下方的concern-area章节仅在代码库中检测到对应技术栈时才包含}

## UI 패턴
- {React/Vue/Angular 등 감지 시: 컴포넌트 구조, 상태 관리 패턴} 翻译为：- {当检测到React/Vue/Angular等时：组件结构、状态管理模式}

## API 패턴
- {Express/Fastify/NestJS/Django 등 감지 시: 엔드포인트 설계, 에러 핸들링 패턴} 翻译为：- {当检测到Express/Fastify/NestJS/Django等时：端点设计、错误处理模式}

## DB 패턴
- {Prisma/TypeORM/Drizzle 등 감지 시: 스키마 규칙, 마이그레이션 패턴} 翻译为：- {当检测到Prisma/TypeORM/Drizzle等时：Schema规则、迁移模式}

concern-area章节（UI模式、API模式、数据库模式、安全模式、基础设施模式）仅在代码库中检测到对应技术栈时才包含。未检测到的技术栈章节不生成。作为初始版本，仅简洁记录核心模式，后续由
```
/bf-update-conventions
```
补充完善。
若文件已存在则跳过。

3. Tech Spec 작성

3. 撰写Tech Spec

아래 템플릿에 따라 Tech Spec 문서를 작성한다:

markdown

undefined

按照以下模板撰写Tech Spec文档：

markdown

undefined

{TICKET} Tech Spec

배경

背景

{변경 목적, 비즈니스 배경, 사용자 문제}

{변경 목적, 비즈니스 배경, 사용자 문제} 翻译为：{变更目的、业务背景、用户问题}

현재 상태 (As-Is)

当前状态（As-Is）

{현재 아키텍처, 관련 모듈 구조, 데이터 흐름} {코드베이스 분석 결과 반영}

{현재 아키텍처, 관련 모듈 구조, 데이터 흐름} 翻译为：{当前架构、相关模块结构、数据流} {코드베이스 분석 결과 반영} 翻译为：{反映代码库分析结果}

목표 상태 (To-Be)

目标状态（To-Be）

{변경 후 아키텍처, 모듈 구조, 데이터 흐름} {주요 설계 결정 및 근거}

{변경 후 아키텍처, 모듈 구조, 데이터 흐름} 翻译为：{变更后的架构、模块结构、数据流} {주요 설계 결정 및 근거} 翻译为：{主要设计决策及依据}

영향 분석

影响分析

변경 대상 파일/모듈: {목록}
의존성 영향: {상위/하위 모듈 영향}
사이드이펙트: {예상되는 부작용}
하위 호환성: {호환성 유지 여부 및 전략}

변경 대상 파일/모듈: {목록} 翻译为：- 变更目标文件/模块: {列表}
의존성 영향: {상위/하위 모듈 영향} 翻译为：- 依赖影响: {上下游模块影响}
사이드이펙트: {예상되는 부작용} 翻译为：- 副作用: {预期的副作用}
하위 호환성: {호환성 유지 여부 및 전략} 翻译为：- 向下兼容性: {是否保持兼容及兼容策略}

인수 조건

{기획자 AC 그대로 포함}

AC 1: {구체적이고 테스트 가능한 기준}
AC 2: ...

{기획자 AC 그대로 포함} 翻译为：{直接包含策划者提供的AC}

AC 1: {구체적이고 테스트 가능한 기준} 翻译为：- [ ] AC 1: {具体且可测试的标准}
AC 2: ...

기술 제약

{성능 요구사항}
{보안 고려사항}
{기존 기술 스택 제약}
{인프라/배포 제약}

{성능 요구사항} 翻译为：- {性能要求}
{보안 고려사항} 翻译为：- {安全考虑事项}
{기존 기술 스택 제약} 翻译为：- {现有技术栈约束}
{인프라/배포 제약} 翻译为：- {基础设施/部署约束}

테스트 전략

단위 테스트: {범위 및 접근}
E2E 테스트: {시나리오 개요}
엣지 케이스: {예상 엣지 케이스 목록}

단위 테스트: {범위 및 접근} 翻译为：- 单元测试: {范围及方法}
E2E 테스트: {시나리오 개요} 翻译为：- E2E测试: {场景概述}
엣지 케이스: {예상 엣지 케이스 목록} 翻译为：- 边缘案例: {预期边缘案例列表}

리스크

리스크	영향도	완화 전략
{리스크 1}	높음/중간/낮음	{전략}

undefined

리스크	영향도	완화 전략
{리스크 1}	높음/중간/낮음	{전략} 翻译为：

undefined

4. 저장 및 커밋

4. 保存及提交

```
docs/tech-specs/{TICKET}-tech-spec.md
```
에 저장한다.
```
docs/tech-specs/
```
디렉토리가 없으면 생성한다.
git commit하지 않는다 — docs/ 산출물은 Phase 4 Archive에서 일괄 커밋한다.

保存至
```
docs/tech-specs/{TICKET}-tech-spec.md
```
若
```
docs/tech-specs/
```
目录不存在则创建
不执行git commit — docs目录下的产出物将在Phase 4 Archive阶段统一提交

5. bf-lead-review 자동 스폰 (Tech-Spec 모드)

5. 自动发起bf-lead-review（Tech-Spec模式）

<HARD-GATE> Tech Spec 작성 후 반드시 bf-lead-review를 스폰하여 다관점 리뷰를 수행한다. 리뷰 없이 사람에게 직접 Tech Spec을 제시하지 않는다. "간단한 변경이라 리뷰가 필요 없다"는 이 게이트를 우회하는 전형적인 합리화이다. </HARD-GATE>

```
bf-lead-review
```
를 스폰한다:
- Task tool 사용,
```
model: opus
```
- 파라미터:
```
mode: "tech-spec"
```
  , tech-spec 경로 전달
메인 세션은
```
"done"
```
+ review.md 경로만 수신한다 (컨텍스트 격리).

<HARD-GATE> 撰写完Tech Spec后必须发起bf-lead-review以开展多视角评审。不得跳过评审直接将Tech Spec呈现给相关人员。“变更简单无需评审”是绕过此关卡的典型借口。 </HARD-GATE>

发起
```
bf-lead-review
```
：
- 使用Task工具，
```
model: opus
```
- 参数：
```
mode: "tech-spec"
```
  ，传递tech-spec路径
主会话仅接收
```
"done"
```
+ review.md路径（上下文隔离）

6. 리뷰 결과 제시 및 사람 개입 ①

6. 呈现评审结果及人工介入点①

<HARD-GATE> 리뷰 결과를 사람에게 반드시 제시하고 승인/수정 판단을 받아야 한다. Blocker가 0이어도 자동 승인하지 않는다. 이것이 사람 판단 ①이며, BF 워크플로우에서 사람이 개입하는 정확히 2개 지점 중 하나이다. </HARD-GATE>

review.md를 읽어서 사람에게 제시한다.
사람의 결정:
- 승인 → "
```
Tech Spec이 승인되었습니다. /bf-execute로 구현을 시작하세요.
```
  " 안내
- 수정 요청 → Tech Spec 수정 후 5단계(bf-lead-review 스폰)를 재실행

<HARD-GATE> 必须将评审结果呈现给相关人员，并获取其批准/修改的判断。即使没有阻塞问题，也不得自动批准。这是人工判断点①，也是BF工作流中仅有的2个人工介入点之一。 </HARD-GATE>

读取review.md并呈现给相关人员
人员决策：
- 批准 → 提示“
```
Tech Spec이 승인되었습니다. /bf-execute로 구현을 시작하세요.
```
  ” 翻译为：“
```
Tech Spec已批准。请使用/bf-execute开始实施。
```
  ”
- 要求修改 → 修改Tech Spec后重新执行第5步（发起bf-lead-review）

Output Format

输出格式

```
docs/tech-specs/{TICKET}-tech-spec.md
```
— Tech Spec 문서
```
docs/reviews/{TICKET}-tech-spec-review.md
```
— 리뷰 결과 (bf-lead-review가 생성)

마크다운 형식. 섹션: 배경, 현재 상태, 목표 상태, 영향 분석, 인수 조건, 기술 제약, 테스트 전략.

```
docs/tech-specs/{TICKET}-tech-spec.md
```
— Tech Spec文档
```
docs/reviews/{TICKET}-tech-spec-review.md
```
— 评审结果（由bf-lead-review生成）

采用Markdown格式。章节包括：背景、当前状态、目标状态、影响分析、验收条件、技术约束、测试策略。