ERP-node/.cursor/rules/agent-pipeline-usage.mdc

---
description: 에이전트 파이프라인 및 멀티에이전트 시스템 사용 규칙
globs:
alwaysApply: true
---

# Agent Pipeline & Multi-Agent System 사용 규칙

## 시스템 개요

이 프로젝트에는 두 가지 멀티에이전트 시스템이 있다:

1. **Orchestrator** (오케스트레이터): 질문/분석 전용. 코드를 읽고 답변만 함.
2. **Pipeline** (파이프라인): 구현/테스트 전용. 코드를 직접 수정하고, 테스트하고, 실패 시 재시도까지 함.

두 시스템 모두 MCP 도구로 호출한다. PM(나)이 직접 처리할 수 있는 단순 작업에는 사용하지 않는다.

---

## 1. PM이 직접 처리하는 경우 (에이전트 안 씀)

다음 경우에는 에이전트를 호출하지 말고 PM이 직접 Read/Write/Shell 도구로 처리:

- 파일 1~5개 읽기/수정
- 단순 코드 검색 (Grep, Glob)
- 단일 도메인 분석 (FE만, BE만, DB만)
- 간단한 버그 수정, 스타일 변경
- git 작업 (커밋, 브랜치, push)
- DB 조회 (SELECT, MCP 직접 호출)

**원칙: 30초 안에 끝나는 작업은 에이전트를 부르지 않는다.**

---

## 2. Orchestrator 도구 (분석/질문용)

### 2.1 사용 가능한 도구

| MCP 도구명 | 용도 | 언제 쓰는가 |
|-----------|------|------------|
| `ask_backend_agent` | BE 전문가에게 질문/분석 요청 | 백엔드 로직 깊은 분석이 필요할 때 |
| `ask_db_agent` | DB 전문가에게 질문/분석 요청 | 복잡한 쿼리 설계, 스키마 분석 필요할 때 |
| `ask_frontend_agent` | FE 전문가에게 질문/분석 요청 | 프론트엔드 구조 깊은 분석 필요할 때 |
| `parallel_ask` | BE+DB+FE 동시 질문 | 크로스도메인 분석 필요할 때 (3개 영역 동시) |

### 2.2 호출 조건

- 사용자가 "분석해줘", "구조 파악해줘", "문제점 찾아줘" 등 분석 요청 시
- 단일 도메인이면 해당 `ask_*_agent` 하나만 호출
- "전체 분석", "크로스도메인", "BE+FE+DB 같이 봐" → `parallel_ask`
- 사용자가 "멀티에이전트" 명시 시 → `parallel_ask`

### 2.3 호출 방법

```
// 단일 에이전트
ask_backend_agent({
  task: "screenManagementService.ts의 saveLayoutV2 함수에서 트랜잭션 처리 현황 분석",
  context: "화면디자이너 V2 보안 점검 중"
})

// 병렬 에이전트
parallel_ask({
  requests: [
    { agent: "backend", task: "V2 API 보안 점검", context: "..." },
    { agent: "db", task: "screen_layouts_v2 제약조건 확인", context: "..." },
    { agent: "frontend", task: "V2 에러 바운더리 적용 현황", context: "..." }
  ]
})
```

### 2.4 주의사항

- Orchestrator는 **코드 수정을 하지 않음** (분석/답변만)
- 응답 시간: 30초~2분
- `parallel_ask`는 3개 에이전트가 동시에 돌아서 시간이 더 걸림
- 에이전트 응답을 받은 후 PM이 사용자에게 요약해서 전달

---

## 3. Pipeline 도구 (구현/테스트용)

### 3.1 사용 가능한 도구

| MCP 도구명 | 용도 | 언제 쓰는가 |
|-----------|------|------------|
| `run_collab` | BE+DB+FE 멀티에이전트 협업 개발 | 크로스도메인 기능 구현 (API+화면+DB 동시) |
| `run_with_retry` | 단일 에이전트 구현 + 테스트 자동 재시도 | 특정 도메인 구현 + 테스트 통과 필요 시 |
| `run_pipeline` | plan.md 기반 자율 실행 | 대규모 계획 순차 실행 시 |
| `run_browser_test` | AI 브라우저 테스트 | 화면 동작 확인 필요 시 |
| `check_collab_status` | collab 진행 상태 확인 | collab 실행 중 상태 체크 |
| `stop_collab` | collab 중지 | collab 실행 중 중단 필요 시 |
| `check_pipeline_status` | pipeline 진행 상태 확인 | pipeline 실행 중 상태 체크 |
| `stop_pipeline` | pipeline 중지 | pipeline 실행 중 중단 필요 시 |

### 3.2 run_collab (멀티에이전트 협업) - 가장 많이 쓰는 도구

**언제 쓰는가**:
- 사용자가 "만들어줘", "구현해줘" + 2개 이상 도메인 관련 시
- "BE+FE 같이", "API랑 화면이랑", "전체적으로 구현" 언급 시
- "협업 모드", "collab" 명시 시
- 테스트 통과할 때까지 자동 반복이 필요할 때

**호출 방법**:
```
run_collab({
  feature: "수주관리 화면에 거래처 검색 기능 추가. 현재 거래처 필드가 entity 타입인데, 검색 가능한 콤보박스로 변경하고, 검색 시 거래처명/코드로 필터링 API 추가",
  agents: ["backend", "frontend"],           // 필요한 에이전트만 (기본: 3개 다)
  maxRounds: 5,                              // 최대 라운드 (기본 5)
  testCommand: "cd frontend && npm run build", // 테스트 명령어 (선택)
  browserTest: "로그인 후 수주관리 화면에서 거래처 검색이 동작하는지 확인" // 브라우저 테스트 (선택)
})
```

**feature 작성 규칙** (매우 중요):
- 구현할 기능을 **자연어로 구체적**으로 기술
- "뭘 만들어라"만 쓰지 말고, "현재 상태 → 원하는 상태"를 명확히
- 관련 파일/테이블/API 경로를 알면 포함
- 모호한 표현 금지 ("좀 고쳐줘", "이전처럼", "알아서")

**좋은 예시**:
```
feature: "screen_layouts_v2 테이블에 version_history JSONB 컬럼 추가.
백엔드: saveLayoutV2 함수에서 저장 시 이전 layout_data를 version_history에 push.
프론트: 화면 디자이너에 '버전 히스토리' 버튼 추가, 클릭 시 이전 버전 목록 표시 및 복원 기능."
```

**나쁜 예시**:
```
feature: "버전 관리 기능 추가해줘"  // 너무 모호
feature: "이전에 했던 거 참고해서"  // 에이전트는 이전 대화 못 봄
```

### 3.3 run_with_retry (단일 에이전트 + 재시도)

**언제 쓰는가**:
- 단일 도메인(BE만, FE만, DB만) 구현이 필요할 때
- "테스트 통과할 때까지" 언급 시
- 특정 에이전트에게만 작업 시킬 때

**호출 방법**:
```
run_with_retry({
  agent: "backend",                        // backend | db | frontend
  task: "adminController.ts에 사용자 검색 API 추가. GET /api/admin/users/search?q=검색어. company_code 필터링 필수.",
  testCommand: "cd backend-node && npm run build",  // 선택
  maxRetries: 3,                           // 기본 3
  workspacePath: "/Users/gbpark/ERP-node"  // 선택
})
```

### 3.4 run_pipeline (plan.md 기반 자율 실행)

**언제 쓰는가**:
- plan.md 파일이 이미 있을 때
- 대규모 작업을 순차적으로 자동 실행할 때
- "파이프라인 실행", "plan.md 돌려" 언급 시

**호출 방법**:
```
// plan.md 파일 경로 지정
run_pipeline({
  planFile: "docs/upgrade-plan.md"
})

// 또는 plan 내용 직접 전달
run_pipeline({
  planContent: "# 작업 계획\n## Task 1\n- agent: backend\n- task: ..."
})
```

### 3.5 run_browser_test (AI 브라우저 테스트)

**언제 쓰는가**:
- 사용자가 "화면에서 확인해봐", "브라우저 테스트", "실제로 돌아가는지 봐" 언급 시
- 구현 후 실제 화면 동작 검증 필요 시

**호출 방법**:
```
run_browser_test({
  instruction: "로그인 페이지에서 admin / admin123으로 로그인 후, 좌측 메뉴에서 '화면관리' 클릭, 수주관리 화면 선택 후 디자이너가 정상 로드되는지 확인",
  baseUrl: "http://localhost:9771",         // 기본값
  loginUrl: "/login",                       // 선택
  loginId: "admin",                         // 선택
  loginPw: "admin123"                       // 선택
})
```

---

## 4. 도구 선택 플로우차트

```
사용자 요청 들어옴
  │
  ├─ 파일 1~5개 수정/간단한 작업? ──→ PM이 직접 처리
  │
  ├─ "분석해줘", "봐줘", "확인해줘"?
  │   ├─ 단일 도메인 ──→ ask_*_agent (해당 도메인)
  │   └─ 크로스도메인 ──→ parallel_ask
  │
  ├─ "만들어줘", "구현해줘", "추가해줘"?
  │   ├─ 단일 도메인 ──→ run_with_retry
  │   ├─ 크로스도메인 ──→ run_collab
  │   └─ plan.md 있음 ──→ run_pipeline
  │
  ├─ "화면에서 확인", "브라우저 테스트"? ──→ run_browser_test
  │
  └─ 진행 상태 / 중지?
      ├─ "상태 확인" ──→ check_collab_status / check_pipeline_status
      └─ "중지" ──→ stop_collab / stop_pipeline
```

---

## 5. 실행 후 모니터링

### 5.1 collab/pipeline 실행 후 반드시 할 일

1. **즉시**: 사용자에게 "실행 시작했어, 예상 N분" 알림
2. **대기**: sleep으로 적절히 대기 (collab: 2~5분, pipeline: 5~15분)
3. **상태 체크**: `check_collab_status` 또는 `check_pipeline_status` 호출
4. **결과 확인**: 
   - 완료 시: 결과 JSON 파일 읽고 사용자에게 요약
   - 실패 시: 에러 내용 확인 후 사용자에게 보고
   - 진행 중: 추가 대기 후 재확인
5. **결과 보고**: 변경된 파일, 성공/실패, 주요 내용 사용자에게 전달

### 5.2 결과 파일 위치

- Collab 결과: `.agent-pipeline/collab/collab-*.json`
- Pipeline 결과: `.agent-pipeline/pipeline-*.json`
- 터미널 출력: `~/.cursor/projects/Users-gbpark-ERP-node/terminals/`

### 5.3 결과 JSON 구조 (collab)

```json
{
  "featureDescription": "구현 기능 설명",
  "round": 3,
  "maxRounds": 5,
  "agents": ["backend", "db", "frontend"],
  "messages": [
    { "round": 1, "from": "backend", "type": "implementation", "content": "..." },
    { "round": 1, "from": "frontend", "type": "question", "content": "[to:backend] ..." }
  ],
  "artifacts": [
    { "agent": "backend", "round": 1, "filePath": "...", "action": "modify", "summary": "..." }
  ],
  "converged": true  // true면 성공, false면 미완료
}
```

---

## 6. 에이전트에게 전달하는 context 작성법

에이전트는 현재 대화를 모른다. `task`와 `context`에 모든 정보를 담아야 한다.

### 필수 포함 정보

1. **현재 상태**: "지금 ~가 ~이렇게 되어 있는데"
2. **원하는 결과**: "~를 ~로 바꿔라" 또는 "~를 새로 만들어라"
3. **관련 파일/경로**: 알고 있으면 정확한 파일 경로 포함
4. **제약조건**: company_code 필터링, 멀티테넌시, 보안 규칙 등
5. **참고 패턴**: "기존 ~함수를 참고해서" (구체적 함수명/파일명)

### 금지 사항

- "이전에 했던 거처럼" → 에이전트는 이전 대화를 모름
- "알아서 해" → 구체적 지시 필요
- "대충" → 결과도 대충 나옴
- 한 번에 10개 이상 작업 요청 → 3~5개로 나눠서

---

## 7. 자주 쓰는 패턴

### 7.1 새 기능 구현 (BE+FE+DB)

```
사용자: "수주관리에 엑셀 내보내기 기능 추가해줘"

PM 판단: 크로스도메인 (BE API + FE 버튼) → run_collab

run_collab({
  feature: "수주관리 화면에 엑셀 내보내기 기능 추가.
  
  백엔드:
  - GET /api/screen-data/:tableName/export 엔드포인트 추가
  - sales_order_mng 테이블 데이터를 엑셀로 변환 (exceljs 사용)
  - company_code 필터링 필수
  
  프론트엔드:
  - InteractiveDataTable.tsx에 '엑셀 내보내기' 버튼 추가
  - 현재 필터링/정렬 조건을 API에 전달
  - 다운로드 완료 시 toast.success 표시",
  
  agents: ["backend", "frontend"],
  testCommand: "cd backend-node && npx tsc --noEmit"
})
```

### 7.2 보안 점검

```
사용자: "이 API 보안 괜찮은지 확인해봐"

PM 판단: 분석 요청 → ask_backend_agent

ask_backend_agent({
  task: "screenManagementService.ts의 모든 screen_layouts_v2 관련 함수에서 company_code 필터링이 누락된 곳 찾기. 코드 라인 인용 필수.",
  context: "멀티테넌시 보안 점검 중. 모든 SELECT/INSERT/UPDATE/DELETE에 company_code 조건 필수."
})
```

### 7.3 브라우저 테스트

```
사용자: "화면에서 잘 되는지 확인해봐"

run_browser_test({
  instruction: "1. http://localhost:9771 접속
  2. admin / 1234 로 로그인
  3. 좌측 메뉴 '화면 관리' > '화면관리' 클릭
  4. '탑셀 영업 수주관리 화면' 선택
  5. 디자이너 화면이 정상 로드되는지 확인
  6. 좌측 컴포넌트 패널에서 아무 컴포넌트를 캔버스에 드래그
  7. 저장 버튼 클릭 후 성공 토스트 확인",
  baseUrl: "http://localhost:9771"
})
```