333 lines
12 KiB
Plaintext
333 lines
12 KiB
Plaintext
---
|
|
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"
|
|
})
|
|
```
|