> ## Documentation Index
> Fetch the complete documentation index at: https://docs.banya.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 채팅 모드
> CodePilot IDE의 세 가지 채팅 모드(CODE / ASK / PLAN)와 각각의 활용법을 설명합니다.
CodePilot IDE는 목적에 따라 세 가지 채팅 모드를 제공합니다. 입력창 좌측 드롭다운에서 언제든지 전환할 수 있습니다.
***
## CODE 모드
**파일을 직접 생성·수정·삭제하고 터미널 명령을 실행하는 기본 모드입니다.**
보내기 버튼: 기본 색상 (투명)
### 할 수 있는 것
* 새 파일 생성 (`create_file`)
* 기존 파일 수정 (`update_file`)
* 파일 삭제 (`delete_file`)
* 터미널 명령 실행 (`run_command`) — `npm install`, `git commit` 등
* 코드 탐색 (파일 읽기, 검색)
* 멀티 에이전트 병렬 실행
### 언제 사용하나요?
* 새 기능 구현, 버그 수정, 리팩터링
* 프로젝트 초기 설정 (패키지 설치, 설정 파일 생성)
* 테스트 코드 작성
* 반복적인 코드 패턴 일괄 수정
### 예시
```
src/hooks/ 디렉토리에 useAuth 커스텀 훅을 만들어줘.
JWT 토큰 저장, 로그인/로그아웃, 자동 갱신 기능을 포함해줘.
```
```
모든 API 호출에 에러 처리가 빠진 부분이 있어. src/api/ 디렉토리 전체를 검토하고 try-catch를 추가해줘.
```
CODE 모드에서는 실제 파일이 변경됩니다. 중요한 작업 전에 Git 커밋 상태를 확인하세요. 인라인 Diff 미리보기에서 Accept/Reject로 변경을 제어할 수 있습니다.
***
## ASK 모드
**파일을 수정하지 않고 질문하고 답변을 받는 모드입니다.**
보내기 버튼: 초록색 (`#10B981`)
### 할 수 있는 것
* 코드 설명 및 분석
* 설계 방향 논의
* 오류 원인 분석
* 문서화, 주석 설명 요청
* 코드 리뷰 의견 요청
### 할 수 없는 것
* 파일 생성·수정·삭제
* 터미널 명령 실행
### 언제 사용하나요?
* 낯선 코드베이스를 처음 파악할 때
* 특정 함수나 클래스의 동작을 이해하고 싶을 때
* 구현 방향을 결정하기 전 조언이 필요할 때
* 코드 변경 없이 리뷰 의견만 받고 싶을 때
### 예시
```
@src/core/orchestration/SubAgentLoop.ts 이 파일이 하는 역할을 설명해줘.
주요 메서드와 데이터 흐름 위주로 알려줘.
```
```
현재 인증 구조에서 보안상 취약한 부분이 있으면 알려줘. 수정은 하지 말고 분석만 해줘.
```
***
## PLAN 모드
**파일을 수정하지 않고 구현 계획을 먼저 수립하는 모드입니다.**
보내기 버튼: 파란색 (`#2563EB`)
### 할 수 있는 것
* 코드베이스 읽기 및 분석 (read-only 탐색)
* 구현 계획 Markdown 출력
* 개요, 분석 결과, 변경 대상 파일, 구현 단계, 리스크, 난이도
### 할 수 없는 것
* 파일 생성·수정·삭제
* 터미널 명령 실행
### 언제 사용하나요?
* 큰 기능을 구현하기 전에 영향 범위를 미리 파악할 때
* 여러 파일에 걸친 변경이 예상될 때
* 팀원과 계획을 공유하고 검토받은 후 실행하고 싶을 때
* AI가 어떻게 구현할지 먼저 확인하고 싶을 때
### 예시
```
결제 시스템을 추가하려고 해. Stripe 연동, 결제 내역 저장, 환불 처리까지 어떻게 구현하면 될까?
```
PLAN 모드는 탐색 후 아래와 같은 형식으로 계획서를 출력합니다:
```markdown theme={null}
## 구현 계획
### 개요
Stripe 결제 시스템 연동 — 결제, 저장, 환불 3단계 구현
### 분석 결과
- 현재 server/api_router.py에 결제 관련 엔드포인트 없음
- DB 스키마에 payments 테이블 미존재
### 변경 대상 파일
- server/payments.py (신규)
- server/api_router.py (수정)
- db/migrations/0003_add_payments.sql (신규)
### 구현 단계
1. Stripe SDK 설치 및 환경 변수 설정
2. payments.py — 결제/환불 비즈니스 로직 구현
3. api_router.py — /api/payments 엔드포인트 추가
4. DB 마이그레이션 실행
### 리스크
- Stripe Webhook 설정 필요 (서버 공개 URL 필요)
### 난이도
중간 (약 2-3시간 예상)
```
### PLAN → CODE 워크플로우
PLAN 모드의 핵심 장점은 **계획 검토 후 실행**입니다.
원하는 기능을 PLAN 모드로 요청합니다. AI가 코드베이스를 탐색하고 계획서를 출력합니다.
변경 대상 파일, 구현 단계, 리스크를 확인합니다. 필요하면 추가 질문으로 계획을 조정합니다.
```
3단계에서 api_router.py 말고 payments_router.py를 새로 만드는 게 낫지 않을까?
```
모드를 CODE로 전환하고 "이 계획대로 구현해줘"라고 요청합니다. 이전 대화에 플랜 내용이 남아있어 AI가 그대로 실행합니다.
```
위 계획대로 구현해줘.
```
***
## AGENT 모드
**LLM이 자율적으로 판단하고 실행하는 완전 자동화 모드입니다.**
보내기 버튼: 검은색
### CODE 모드와의 차이
| | CODE 모드 | AGENT 모드 |
| --------- | --------------------------- | -------------------------- |
| **작업 흐름** | 시스템이 관리 (조사→실행→검증→완료) | LLM이 자율 판단 |
| **빌드 검증** | 자동 실행 (tsc, dotnet build 등) | LLM이 필요 시 직접 실행 |
| **에러 수정** | repair agent 자동 생성 | LLM이 스스로 판단 |
| **작업 계획** | 시스템이 FSM으로 관리 | `work_plan` 도구로 LLM이 직접 관리 |
| **워커 생성** | 시스템이 자동 분할 (멀티에이전트) | `spawn_agent`로 LLM이 직접 생성 |
| **속도** | 안정적이지만 검증 시간 추가 | 빠르지만 LLM 품질에 의존 |
### 할 수 있는 것
* CODE 모드의 모든 기능 (파일 생성·수정·삭제, 터미널 실행)
* **작업 계획 수립** (`work_plan`) — 작업 큐 UI에 진행 상황 표시
* **워커 에이전트 생성** (`spawn_agent`) — 복잡한 작업을 서브 에이전트에게 위임
* **자율적 판단** — 몇 개 파일을 읽고, 어떤 순서로 수정하고, 검증할지 LLM이 결정
### 안전장치
* **에러 누적 감지**: 같은 도구가 3회 연속 실패하면 "다른 방법을 시도하세요" 프롬프트 자동 삽입
* **턴 수 경고**: 25턴 중 20턴에 도달하면 LLM에 "남은 턴 5회" 알림 — 작업 마무리 유도
* **파일 롤백**: 모든 변경 사항을 턴 단위로 되돌리기 가능 (Undo Turn)
### 언제 사용하나요?
* 복잡한 멀티파일 작업을 LLM에게 완전히 맡기고 싶을 때
* 빌드 검증 없이 빠르게 결과를 얻고 싶을 때
* LLM이 작업 순서를 스스로 판단하는 것이 더 효율적일 때
### 예시
```
프론트에 설정 페이지 만들어주고, 백엔드에 복지 카테고리 CRUD API 추가해줘.
둘 다 완성되면 연동해줘.
```
```
이 프로젝트의 전체 테스트를 실행하고, 실패하는 것들을 모두 수정해줘.
```
AGENT 모드는 LLM의 자율 판단에 의존하므로, LLM 품질에 따라 결과가 달라질 수 있습니다. 안정적인 결과가 필요하면 CODE 모드를 사용하세요.
***
## 모드 비교 요약
| | CODE | ASK | PLAN | AGENT |
| -------------------- | ------------- | ----- | ----- | ------------- |
| 파일 읽기 | ✅ | ✅ | ✅ | ✅ |
| 파일 생성·수정·삭제 | ✅ | ❌ | ❌ | ✅ |
| 터미널 명령 실행 | ✅ | ❌ | ❌ | ✅ |
| 멀티 에이전트 | ✅ (시스템 자동 분할) | ✅ | ✅ | ✅ (LLM 자율 판단) |
| 작업 계획 (work\_plan) | ❌ | ❌ | ❌ | ✅ |
| 워커 생성 (spawn\_agent) | ❌ | ❌ | ❌ | ✅ |
| 자동 빌드 검증 | ✅ | ❌ | ❌ | ❌ |
| 자동 에러 수정 | ✅ | ❌ | ❌ | ❌ |
| 보내기 버튼 색상 | 기본 | 초록 | 파란 | 검정 |
| 주요 용도 | 안정적 구현 | 질문·분석 | 계획 수립 | 자율 구현 |