지난 포스팅에서 PI를 설치하고 Nvidia 무료 API 키까지 발급받았습니다. 이번엔 본격적으로 PI를 어떻게 쓰는지, 그리고 PI의 진짜 강점인 서브에이전트(subagent)로 작업을 나눠 맡기는 법까지 다뤄보겠습니다.
이 글은 PI 공식 문서를 기반으로 작성했습니다.
1. PI 실행하고 첫 작업 시키기
설치가 끝났다면 작업할 프로젝트 폴더로 이동해서 pi 만 입력하면 됩니다.
cd /path/to/project
pi처음 실행하면 로그인을 요구합니다. 두 가지 방법이 있습니다.
① 구독 계정 연결 — 채팅창에 /login 을 입력하면 Claude Pro/Max, ChatGPT Plus/Pro, GitHub Copilot 같은 구독 제공사를 고를 수 있습니다.
② API 키 사용 — 지난 글에서 발급한 키처럼, 환경 변수로 키를 넣고 실행합니다.
export ANTHROPIC_API_KEY=sk-ant-...
piNvidia 무료 키를 쓰신다면 지난 포스팅에서 등록한 그대로
/model로 Kimi 2.6을 선택하시면 됩니다.
로그인이 끝나면 그냥 한국어로 시키고 싶은 작업을 입력하면 됩니다.
이 저장소가 뭐 하는 프로젝트인지 요약하고, 테스트는 어떻게 돌리는지 알려줘.PI는 기본적으로 read(읽기), write(쓰기), edit(수정), bash(명령 실행) 네 가지 도구를 가지고 스스로 파일을 읽고 고칩니다. 파일을 수정할 때는 변경 내용을 먼저 보여주고 적용 여부를 물어보니, 마음에 안 들면 거절하면 됩니다.
2. 파일을 컨텍스트에 넣기 — @ 문법
“이 파일 좀 봐줘”라고 할 때는 @ 뒤에 경로를 붙입니다. 터미널에서 바로 한 줄로도 가능합니다.
pi @README.md "이 파일 요약해줘"
pi @src/app.ts @src/app.test.ts "이 둘을 같이 보고 리뷰해줘"이미지도 넣을 수 있습니다.
pi @screenshot.png "이 화면에 뭐가 보여?"여러 파일을 한 번에 던질수록 좋은 게 아니라, 필요한 파일만 골라 넣는 것이 응답 품질과 토큰 절약 모두에 유리합니다.
3. 셸 명령 실행 — ! 문법
인터랙티브 모드 안에서 셸 명령을 바로 돌리려면 앞에 ! 를 붙입니다.
!npm run lint명령 결과를 모델에게는 보내지 않고 나만 확인하고 싶다면 !! 를 씁니다.
!!git status터미널을 따로 열지 않아도 되니 작업 흐름이 끊기지 않습니다.
4. 프로젝트 규칙 주입 — AGENTS.md / CLAUDE.md
프로젝트 루트에 AGENTS.md 또는 CLAUDE.md 파일을 두면, PI가 매번 그 규칙을 지키며 작업합니다.
- 코드를 고친 뒤에는 항상 `npm run check` 를 실행할 것.
- 답변은 간결하게.
- 사용자에게 보이는 문구는 한국어로 작성할 것.“매번 이거 하라고 시키기 귀찮은” 규칙들을 여기에 적어두면 됩니다.
5. 모델 전환과 세션 관리
자주 쓰는 슬래시 명령어와 세션 옵션입니다.
| 명령어 | 역할 |
|---|---|
/model | 사용할 모델 전환 |
/settings | 사고(thinking) 수준·테마 등 설정 |
/new | 새 세션 시작 |
/resume | 이전 세션 불러오기 |
/compact | 길어진 대화를 요약해 컨텍스트 정리 |
터미널에서 세션을 이어가는 옵션도 있습니다.
pi -c # 가장 최근 세션 이어가기
pi -r # 세션 목록에서 골라 이어가기
pi --name "작업이름" # 이름 붙여서 새 세션 시작작업 하나가 끝나면 /new 로 깔끔하게 비우고 시작하는 습관을 들이면, 이전 맥락이 끼어들어 엉뚱한 답을 내놓는 일을 줄일 수 있습니다.
6. 핵심 — 서브에이전트로 작업 분배하기
여기서부터가 PI의 진짜 매력입니다.
먼저 알아둘 사실: PI는 기본 상태에선 서브에이전트(sub-agent)와 plan mode를 일부러 넣지 않았습니다. 공식 문서도 “Pi는 강력한 기본값을 제공하지만 서브에이전트와 plan mode 같은 기능은 빼두었다”고 밝히고 있습니다. 대신 필요하면 패키지로 끼워 넣는 방식입니다.
작업 분배 기능은 공식 pi-subagents 패키지로 추가합니다.
pi install npm:pi-subagents설치하면 PI가 작업을 여러 개의 집중된 자식 에이전트에게 나눠 맡길 수 있게 됩니다. 자식 에이전트는 자기만의 임무를 가진 독립된 PI 세션이고, 일을 끝내면 결과를 부모에게 돌려줍니다.
제공되는 서브에이전트 역할
| 역할 | 하는 일 |
|---|---|
| scout | 코드베이스 빠른 정찰 — 관련 파일·진입점·데이터 흐름·위험요소 파악 |
| researcher | 웹/문서 조사 후 출처와 함께 간결한 브리핑 |
| planner | 기존 맥락을 바탕으로 구체적인 구현 계획 작성 |
| worker | 승인된 변경을 실제로 구현 (파일 수정) |
| reviewer | 구현이 작업/계획과 맞는지 코드 리뷰 + 소소한 수정 |
| context-builder | 더 강한 사전 조사 — 코드 맥락 수집 후 인수인계 자료 작성 |
| oracle | 파일은 안 건드리고 방향성에 대해 제2의 의견을 주는 조언자 |
| delegate | 부모 동작을 그대로 따르는 범용 자식 에이전트 |
어떻게 시키나? — 그냥 말로 하면 됩니다
복잡한 슬래시 명령을 외울 필요 없이, 자연어로 위임하면 됩니다. 공식 예시를 그대로 옮기면:
이 diff를 reviewer한테 리뷰 시켜줘.
지금 내 계획에 대해 oracle한테 제2의 의견을 물어봐줘.
scout로 이 코드를 파악한 다음, 모르는 건 나한테 질문해줘.
worker한테 이 승인된 계획을 구현시키고, reviewer 돌려서 수정사항까지 반영해줘.여러 명을 동시에 — 병렬 실행
여러 관점이 필요할 땐 자식 에이전트를 동시에 띄울 수 있습니다.
reviewer 셋을 병렬로 돌려줘. 하나는 정확성, 하나는 테스트, 하나는 불필요한 복잡도를 봐줘.PI가 각 결과를 구분선과 함께 한데 모아서 정리해 줍니다.
한 줄로 이어붙이기 — 추천 워크플로우
실전에서 자주 쓰는 흐름은 정찰 → 계획 → 구현 → 리뷰 순서입니다.
먼저 scout로 인증(auth) 관련 코드를 훑고,
그 내용으로 planner가 구현 계획을 세운 다음,
worker가 구현하고, 마지막에 reviewer가 점검해서 고쳐줘.앞 단계의 결과가 다음 단계로 자연스럽게 넘어갑니다.
알아두면 좋은 옵션
-
백그라운드 실행: 오래 걸리는 작업은 비동기로 돌려두고 다른 일을 할 수 있습니다.
-
역할별 모델 지정:
~/.pi/agent/settings.json에서 서브에이전트마다 다른 모델을 쓰도록 덮어쓸 수 있습니다. 예를 들어 리뷰는 더 똑똑한 모델로:{ "subagents": { "agentOverrides": { "reviewer": { "model": "anthropic/claude-sonnet-4", "thinking": "high" } } } } -
설정 점검: 뭔가 잘 안 되면
/subagents-doctor로 설치 상태를 진단할 수 있습니다.
마치며
이제 PI로 파일을 다루고(@), 명령을 돌리고(!), 세션을 관리하고, 나아가 여러 서브에이전트에게 작업을 나눠 맡기는 것까지 할 수 있게 됐습니다. 혼자서 모든 걸 처리하던 코딩 에이전트가, 정찰·계획·구현·리뷰를 분업하는 작은 팀처럼 움직이는 셈입니다.
다음 포스팅에서는 pi install 로 설치할 수 있는 다른 유용한 커뮤니티 패키지들과, 나만의 워크플로우를 패키지로 묶어 공유하는 방법을 살펴보겠습니다. 감사합니다!