Back to Details

code-review-team

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Review & Team Refactor

代码审查与团队重构

프로젝트의 규칙/스킬/에이전트 설정을 먼저 파악하고, 그에 맞는 전문가 관점으로 리뷰합니다. 사용자가 개선 범위를 지정하면 Agent Team을 스폰하여 병렬로 수정합니다.
首先掌握项目的规则/技能/Agent设置，然后从符合项目需求的专家视角进行审查。当用户指定优化范围后，将生成Agent Team并行进行修改。

전체 흐름

整体流程

Phase 1: 컨텍스트 탐색 → 전문가 패널 구성 → 리뷰 → 사용자 전달
  ── 사용자 검토 (개선 범위 지정) ──
Phase 2: 범위 확정 → TeamCreate → 병렬 개선 → 완료 보고
Phase 1: 上下文探索 → 专家小组组建 → 审查 → 交付用户
  ── 用户审核（指定优化范围）──
Phase 2: 范围确认 → TeamCreate → 并行优化 → 完成报告

Phase 1: 코드 리뷰

Phase 1: 代码审查

Step 1. 프로젝트 컨텍스트 탐색

Step 1. 项目上下文探索

변경 사항을 보기 전에 프로젝트 설정을 파악합니다.
탐색 대상 (순서대로):
우선순위경로파악할 내용
1
CLAUDE.md
, 
.claude/CLAUDE.md
프로젝트 개요, 핵심 규칙, 컨벤션
2
.claude/settings.json
허용 도구, 권한 설정
3
.claude/skills/*/SKILL.md
(frontmatter만)		프로젝트가 사용하는 스킬 목록
4
.claude/agents/*/AGENT.md
(frontmatter만)		등록된 에이전트 역할
5프로젝트 루트 설정 파일
package.json
, 
pyproject.toml
, 
go.mod
등 → 언어/프레임워크 판별
6lint/format 설정
.eslintrc
, 
ruff.toml
, 
.prettierrc
등 → 코드 스타일 규칙
결과물: 프로젝트 프로파일 요약
프로젝트 프로파일:
- 언어/프레임워크: {감지 결과}
- 핵심 규칙: {CLAUDE.md에서 추출한 규칙들}
- 코드 스타일: {lint/format 설정 요약}
- 등록된 스킬: {스킬 목록}
- 등록된 에이전트: {에이전트 목록}
在查看变更内容之前，先掌握项目设置。
探索对象（按顺序）：
优先级路径需要掌握的内容
1
CLAUDE.md
, 
.claude/CLAUDE.md
项目概述、核心规则、约定
2
.claude/settings.json
允许使用的工具、权限设置
3
.claude/skills/*/SKILL.md
（仅frontmatter）		项目使用的技能列表
4
.claude/agents/*/AGENT.md
（仅frontmatter）		已注册的Agent角色
5项目根目录设置文件
package.json
, 
pyproject.toml
, 
go.mod
等 → 判别语言/框架
6lint/格式设置
.eslintrc
, 
ruff.toml
, 
.prettierrc
等 → 代码风格规则
产出物：项目配置概要
项目配置概要:
- 语言/框架: {检测结果}
- 核心规则: {从CLAUDE.md提取的规则}
- 代码风格: {lint/格式设置概要}
- 已注册技能: {技能列表}
- 已注册Agent: {Agent列表}

Step 2. 전문가 패널 구성

Step 2. 专家小组组建

프로젝트 프로파일을 기반으로 리뷰에 참여할 전문가 관점을 동적으로 결정합니다.
전문가 패널 구성 가이드 참조.
기본 관점 (항상 포함):
  • 프로젝트 규칙 준수 — CLAUDE.md, lint 설정 등 프로젝트 자체 규칙 위반 여부
  • 정확성 — 로직 오류, 에러 처리, 엣지 케이스
조건부 관점 (프로파일에 따라 추가):
  • 웹 프레임워크 감지 → 보안 관점 추가
  • DB/ORM 감지 → 데이터 계층 관점 추가
  • 테스트 프레임워크 감지 → 테스트 커버리지 관점 추가
  • 등등 (상세는 references 참조)
基于项目配置概要，动态确定参与审查的专家视角。
参考专家小组组建指南。
基础视角（必选）：
  • 项目规则合规性 — 检查是否违反CLAUDE.md、lint设置等项目自身规则
  • 准确性 — 逻辑错误、异常处理、边缘情况
条件视角（根据配置概要添加）：
  • 检测到Web框架 → 添加安全视角
  • 检测到DB/ORM → 添加数据层视角
  • 检测到测试框架 → 添加测试覆盖率视角
  • 等等（详情参考references）

Step 3. 변경 사항 분석

Step 3. 变更内容分析

다음 우선순위에 따라 diff 범위를 결정합니다.
按以下优先级确定diff范围。

3-1. Diff 범위 결정

3-1. Diff范围确定

우선순위조건diff 범위
1사용자가 커밋/태그 지정
git diff <ref>..HEAD
2피처 브랜치 (비-기본 브랜치)
git diff $(git merge-base <base> HEAD)..HEAD
3Fallback사용자에게 질문
베이스 브랜치 자동 탐지 (Priority 2에서 사용):
bash
undefined
优先级条件diff范围
1用户指定了提交/标签
git diff <ref>..HEAD
2功能分支（非主分支）
git diff $(git merge-base <base> HEAD)..HEAD
3备选方案询问用户
主分支自动检测（用于优先级2）：
bash
undefined

존재하는 첫 번째 브랜치를 베이스로 사용

使用第一个存在的分支作为基准

for base in origin/dev origin/develop origin/main; do git rev-parse --verify "$base" &>/dev/null && break done

**기본 브랜치 판별**: `dev`, `develop`, `main`, `master` 중 하나면 기본 브랜치로 간주.
for base in origin/dev origin/develop origin/main; do git rev-parse --verify "$base" &>/dev/null && break done

**主分支判别**：若为`dev`, `develop`, `main`, `master`中的一个，则视为基准分支。

3-2. TICKET_ID 추출

3-2. TICKET_ID提取

bash
git branch --show-current
브랜치명에서 TICKET_ID 패턴 추출:
  • feature/ABC-123-desc
    → 
    ABC-123
  • fix/PROJ-456
    → 
    PROJ-456
  • ABC-123-some-desc
    → 
    ABC-123
  • 패턴: 
    [A-Z]+-[0-9]+
    (첫 매칭)
  • 실패 시 → 사용자에게 질문
bash
git branch --show-current
从分支名中提取TICKET_ID模式：
  • feature/ABC-123-desc
    → 
    ABC-123
  • fix/PROJ-456
    → 
    PROJ-456
  • ABC-123-some-desc
    → 
    ABC-123
  • 模式: 
    [A-Z]+-[0-9]+
    （第一个匹配项）
  • 提取失败时 → 询问用户

3-3. 변경 사항 수집

3-3. 变更内容收集

bash
git diff {범위} --name-only    # 변경 파일 목록
git diff {범위}                 # 전체 diff
git log {범위} --oneline        # 커밋 히스토리 (컨텍스트 파악용)
bash
git diff {范围} --name-only    # 变更文件列表
git diff {范围}                 # 完整diff
git log {范围} --oneline        # 提交历史（用于掌握上下文）

Step 4. 리뷰 수행

Step 4. 执行审查

각 전문가 관점에서 변경된 코드를 검토합니다.
리뷰 원칙:
  • 프로젝트 컨텍스트 우선 — 일반론보다 이 프로젝트의 규칙/컨벤션 기준으로 판단
  • 이슈 위치를 정확히 지정 (파일:라인)
  • 왜 문제인지 근거 제시
  • 개선 방향을 제안하되, 구체적 수정 코드는 Phase 2에서 처리
이슈 등급:
등급기준
CRITICAL보안 취약점, 데이터 손실, 시스템 장애 유발
MAJOR기능 오류, 프로젝트 핵심 규칙 위반, 심각한 성능 저하
MEDIUM코드 품질, 컨벤션 불일치, 유지보수 어려움
LOW사소한 개선, 스타일
从各专家视角审查变更后的代码。
审查原则：
  • 项目上下文优先 — 优先依据本项目的规则/约定判断，而非通用准则
  • 准确定位问题位置（文件:行号）
  • 说明问题产生的原因
  • 提出优化方向，但具体修改代码在Phase 2中处理
问题等级：
等级标准
CRITICAL安全漏洞、数据丢失、可能导致系统故障
MAJOR功能错误、违反项目核心规则、严重性能下降
MEDIUM代码质量、约定不一致、维护困难
LOW微小优化、风格问题

Step 5. 리뷰 문서 저장 및 전달

Step 5. 审查文档保存与交付

경로: 
.ai/tasks/{TICKET_ID}/review.md
형식: 리뷰 문서 템플릿
기존 파일 있으면 
review-01.md
, 
review-02.md
로 버전 증가.
사용자에게 전달:
📋 코드 리뷰 완료
📄 문서: .ai/tasks/{TICKET_ID}/review.md

프로젝트 컨텍스트: {언어}, {프레임워크}, {핵심 규칙 요약}
리뷰 관점: {적용된 전문가 목록}

| 등급 | 건수 |
|------|------|
| 🔴 CRITICAL | N |
| 🟠 MAJOR | N |
| 🟡 MEDIUM | N |
| 🟢 LOW | N |

주요 이슈:
1. src/auth.ts:45 — [보안] 사용자 입력 검증 누락
2. src/service.ts:120 — [프로젝트 규칙] CLAUDE.md의 에러 처리 규칙 미준수
...

개선을 진행하려면 범위를 지정해주세요.
예: "CRITICAL 전부", "1, 3번", "전부"
路径: 
.ai/tasks/{TICKET_ID}/review.md
格式: 审查文档模板
若存在现有文件，则按
review-01.md
, 
review-02.md
递增版本。
交付给用户：
📋 代码审查完成
📄 文档: .ai/tasks/{TICKET_ID}/review.md

项目上下文: {语言}, {框架}, {核心规则概要}
审查视角: {适用的专家列表}

| 等级 | 数量 |
|------|------|
| 🔴 CRITICAL | N |
| 🟠 MAJOR | N |
| 🟡 MEDIUM | N |
| 🟢 LOW | N |

主要问题:
1. src/auth.ts:45 — [安全] 缺少用户输入验证
2. src/service.ts:120 — [项目规则] 未遵守CLAUDE.md的异常处理规则
...

若要进行优化，请指定范围。
示例: "全部CRITICAL问题", "第1、3项", "全部"

Phase 2: 팀 개선

Phase 2: 团队优化

사용자가 범위를 지정하면 Agent Team을 스폰합니다.
当用户指定范围后，将生成Agent Team。

Step 1. 범위 확정 및 작업 그룹핑

Step 1. 范围确认与任务分组

대상 이슈를 파일 단위로 그룹핑:
  • 같은 파일 / 의존 관계 파일 → 하나의 Task
  • 독립 파일 → 별도 Task
  • 최대 Worker 5명
将目标问题按文件维度分组:
  • 同一文件/依赖文件 → 单个Task
  • 独立文件 → 单独Task
  • 最多5个Worker

Step 2. Team SPAWN

Step 2. Team SPAWN

팀 스폰 상세 가이드 참조.
다음 절차를 순서대로 실행합니다.
参考团队生成详细指南。
按以下顺序执行步骤。

2-1. 팀 생성

2-1. 团队创建

TeamCreate
도구를 호출합니다.
파라미터값
team_name
"review-{TICKET_ID}"
description
"{TICKET_ID} 코드 리뷰 이슈 개선"
调用
TeamCreate
工具。
参数值
team_name
"review-{TICKET_ID}"
description
"{TICKET_ID} 代码审查问题优化"

2-2. 태스크 생성

2-2. 任务创建

이슈 그룹마다 
TaskCreate
도구를 호출합니다. 모든 태스크를 동시에 생성합니다.
파라미터값
subject
"개선: {파일명} ({이슈 수}건)"
description
프로젝트 컨텍스트 + 담당 파일 + 수정할 이슈 목록
activeForm
"{파일명} 개선 중"
为每个问题组调用
TaskCreate
工具。所有任务同时创建。
参数值
subject
"优化: {文件名}（{问题数量}项）"
description
项目上下文 + 负责文件 + 待修改问题列表
activeForm
"{文件名} 优化中"

2-3. Worker 스폰

2-3. Worker生成

이슈 그룹 수만큼 
Task
도구를 호출하여 Worker를 스폰합니다. 모든 Worker를 동시에 스폰합니다.
파라미터값
subagent_type
"general-purpose"
team_name
"review-{TICKET_ID}"
name
"refactor-worker-{N}"
(1부터 순번)
description
"코드 개선 Worker {N}"
mode
"bypassPermissions"
prompt
Worker 프롬프트 (아래 참조)
Worker 프롬프트에 반드시 포함할 내용:
  • 프로젝트 규칙/컨벤션 (CLAUDE.md에서 추출한 핵심 규칙)
  • 담당 파일 및 이슈 목록 (리뷰 문서에서 해당 그룹의 이슈 전체)
  • 이슈별 개선 방향
  • 작업 절차 지시 (TaskList → TaskUpdate in_progress → 파일 수정 → SendMessage로 리더에게 보고 → TaskUpdate completed)
  • 담당 파일만 수정하라는 규칙
Worker 프롬프트 상세 템플릿은 팀 스폰 상세 가이드를 참조합니다.
根据问题组数量调用
Task
工具生成Worker。所有Worker同时生成。
参数值
subagent_type
"general-purpose"
team_name
"review-{TICKET_ID}"
name
"refactor-worker-{N}"
（从1开始编号）
description
"代码优化Worker {N}"
mode
"bypassPermissions"
prompt
Worker提示词（参考下文）
Worker提示词必填内容:
  • 项目规则/约定（从CLAUDE.md提取的核心规则）
  • 负责文件及问题列表（审查文档中对应组的所有问题）
  • 各问题的优化方向
  • 工作流程指示（TaskList → TaskUpdate in_progress → 文件修改 → 通过SendMessage向负责人报告 → TaskUpdate completed）
  • 仅修改负责文件的规则
Worker提示词详细模板请参考团队生成详细指南。

2-4. 태스크 할당

2-4. 任务分配

Worker가 스폰되면 
TaskUpdate
도구로 각 Worker에게 Task를 할당합니다.
파라미터값
taskId
해당 태스크 ID
owner
"refactor-worker-{N}"
(Worker name과 동일)
Worker生成后，通过
TaskUpdate
工具为每个Worker分配Task。
参数值
taskId
对应任务ID
owner
"refactor-worker-{N}"
（与Worker名称一致）

2-5. 완료 대기

2-5. 等待完成

Worker들이 작업을 완료하면 
SendMessage
로 결과를 보고합니다. 자동으로 수신됩니다. 모든 Worker의 보고가 도착할 때까지 대기합니다.
Worker完成工作后，将通过
SendMessage
报告结果，系统会自动接收。等待所有Worker的报告到达。

Step 3. 정리 및 보고

Step 3. 整理与报告

3-1. Worker 종료

3-1. Worker终止

모든 Worker에게 
SendMessage
도구로 종료를 요청합니다.
파라미터값
type
"shutdown_request"
recipient
"refactor-worker-{N}"
content
"작업 완료. 종료합니다."
通过
SendMessage
工具向所有Worker发送终止请求。
参数值
type
"shutdown_request"
recipient
"refactor-worker-{N}"
content
"工作完成，即将终止。"

3-2. 팀 삭제

3-2. 团队删除

모든 Worker가 종료된 후 
TeamDelete
도구를 호출합니다.
所有Worker终止后，调用
TeamDelete
工具。

3-3. 완료 보고

3-3. 完成报告

✅ 개선 완료

수정된 이슈: N/M건
수정된 파일:
- src/auth.ts: 2건 (입력 검증 추가, 에러 처리 규칙 적용)
- ...

팀 정리 완료. 커밋하시려면 말씀해주세요.
✅ 优化完成

已修改问题: N/M项
已修改文件:
- src/auth.ts: 2项（添加输入验证、应用异常处理规则）
- ...

团队已清理。如需提交请告知。

상세 가이드

详细指南

  • 전문가 패널 구성
  • 리뷰 문서 템플릿
  • 팀 스폰 상세 가이드
  • 专家小组组建
  • 审查文档模板
  • 团队生成详细指南