[Pi 시리즈 1편] 무거워진 코딩 에이전트 대신 pi를 보는 이유

요즘 LLM 코딩 에이전트를 쓰면서 가장 크게 느끼는 문제는 모델 성능보다 작업 흐름의 무거움입니다.

처음에는 도구가 많을수록 좋다고 생각했습니다. 파일을 읽고, 명령을 실행하고, 브라우저를 열고, MCP 서버를 붙이고, 서브에이전트를 부르고, 자동 계획까지 세워주면 더 빠르게 일할 수 있을 것 같았습니다. 여기서 MCP는 Model Context Protocol의 줄임말로, 외부 도구나 서비스를 LLM 클라이언트에 연결하기 위한 표준 방식입니다. 서브에이전트는 큰 작업을 별도의 하위 에이전트에게 나누어 맡기는 구조를 말합니다.

그런데 실제로 하루 종일 쓰다 보면 다른 문제가 생깁니다. 응답이 느려지고, 작은 수정 하나에도 툴콜이 길게 이어지고, 세션이 길어질수록 이전 맥락이 현재 작업을 밀어냅니다. 체감상 예전보다 같은 시간에 끝내는 작업량이 절반도 안 되는 날도 있습니다.

그래서 이번 시리즈에서는 반대 방향의 도구를 살펴보려고 합니다. pi는 가볍고 작게 시작하는 것을 목표로 한 터미널 코딩 하네스입니다. 여기서 pi는 수학 상수 π가 아니라 도구 이름입니다. 하네스는 LLM과 파일 시스템, 셸 명령, 편집 도구를 연결해 실제 작업을 실행하게 해주는 틀을 뜻합니다.

이 글에서 할 것

이번 글은 pi의 설치법까지 한 번에 다루지 않습니다. 먼저 왜 pi를 보게 되었는지, 그리고 pi가 어떤 철학을 가진 도구인지에 집중합니다.

LLM 코딩 에이전트가 느려졌다고 느끼는 이유
툴콜과 컨텍스트가 많아질 때 생기는 생산성 저하
pi가 선택한 미니멀한 설계 철학
pi가 잘 맞는 사람과 덜 맞는 사람

설치와 첫 실행은 다음 글에서 따로 다룹니다.

왜 다시 가벼운 하네스가 필요해졌나

내가 사용해 온 일부 LLM 코딩 도구는 한동안 더 많은 기능을 붙이는 방향으로 발전했습니다.

처음에는 웹 채팅에서 코드를 복사하고 붙여넣는 것만으로도 충분히 놀라웠습니다. 그다음에는 IDE 안에서 파일을 읽고 수정하는 에이전트가 나왔고, 이후에는 터미널 기반 CLI 에이전트와 MCP 서버, 서브에이전트, 플랜 모드, 자동 TODO, 권한 확인 UI 같은 기능들이 빠르게 붙었습니다.

기능이 늘어난 것 자체가 문제는 아닙니다. 복잡한 작업을 할 때는 이런 기능이 분명히 도움이 됩니다. 문제는 모든 작업이 복잡한 작업은 아니라는 점입니다.

예를 들어 실제 개발 중에는 이런 요청이 훨씬 자주 나옵니다.

이 파일의 흐름을 설명해줘.
이 컴포넌트에서 변수 이름만 더 명확하게 바꿔줘.
방금 실패한 테스트 로그를 보고 원인을 찾아줘.
블로그 글 하나의 frontmatter와 문단 흐름을 정리해줘.
npm run check 결과를 보고 수정해야 할 파일을 찾아줘.

이런 일에는 거창한 플래너나 여러 단계의 서브에이전트보다, 빠르게 파일을 읽고 필요한 부분만 고친 뒤 결과를 확인하는 루프가 더 중요합니다.

책상 위에 모든 공구를 다 꺼내놓으면 무엇이든 할 수는 있습니다. 하지만 드라이버 하나만 필요한 상황에서도 공구 더미 속에서 드라이버를 찾느라 시간이 걸립니다. 요즘의 무거운 코딩 에이전트가 가끔 그렇게 느껴집니다.

느려지는 이유를 하네스 관점에서 보기

LLM 코딩 에이전트의 속도 문제는 단순히 “모델이 느리다”로만 설명하기 어렵습니다. 실제 속도는 모델, provider, 네트워크 상태, 프로젝트 크기에도 영향을 받습니다. 여기에 더해 하네스가 모델에게 어떤 정보를 주고, 어떤 도구를 노출하고, 어떤 절차를 강제하는지도 큰 영향을 줍니다.

첫 번째 문제는 도구 선택 비용입니다. 도구가 많으면 모델은 매 응답마다 어떤 도구를 써야 하는지 판단해야 합니다. 각 도구의 설명도 컨텍스트에 들어갑니다. 도구가 많아질수록 모델이 읽고 비교해야 할 선택지가 늘어납니다.

두 번째 문제는 컨텍스트 비대화입니다. MCP 서버 설명, 확장 기능 설명, 긴 시스템 프롬프트, 이전 대화, 자동 계획, TODO 목록이 한꺼번에 쌓이면 실제 작업 파일보다 주변 정보가 더 커질 수 있습니다.

세 번째 문제는 작업 단위의 과도한 자동화입니다. 작은 변경에도 계획을 세우고, 확인을 요청하고, 여러 도구를 호출하고, 다시 요약하는 흐름이 붙으면 응답 하나의 왕복 시간이 길어집니다.

물론 기능이 풍부한 에이전트 하네스가 나쁘다는 뜻은 아닙니다. OpenCode, omo 같은 에이전트 기반 환경은 강력한 자동화와 확장성을 제공합니다. 나도 그런 도구들 덕분에 복잡한 작업을 많이 줄였습니다. 다만 최근에 겪은 문제는, 그 풍부함이 매번 필요한 것은 아닌데도 매번 비용으로 돌아온다는 점이었습니다.

pi는 어떤 도구인가

pi는 공식적으로 minimal terminal coding harness를 지향합니다. 말 그대로 터미널에서 쓰는 작은 코딩 에이전트 하네스입니다.

설치하고 실행하면 기본적으로 모델에게 파일 읽기, 파일 쓰기, 부분 수정, 셸 명령 실행 같은 코딩 작업의 핵심 도구를 제공합니다. 공식 Quick Start에서는 기본 도구로 read, write, edit, bash를 중심에 둡니다. CLI 옵션 기준으로는 read, bash, edit, write, grep, find, ls 같은 내장 도구를 사용할 수 있습니다.

중요한 점은 pi가 “기능이 없는 도구”가 아니라는 것입니다. pi는 기능을 코어에 모두 넣지 않습니다. 대신 필요한 기능을 아래 방식으로 붙일 수 있게 합니다.

확장 방식	역할
Prompt Templates	반복해서 쓰는 프롬프트를 명령처럼 불러오기
Skills	특정 작업 절차나 사용 조건을 `SKILL.md` 문서로 정의해 필요할 때 불러오기
Extensions	TypeScript로 도구, 명령, UI, 이벤트 처리 등을 추가하기
Themes	터미널 UI 스타일 바꾸기
Pi Packages	확장, 스킬, 템플릿, 테마를 묶어 npm이나 git으로 공유하기

즉 pi는 완성형 올인원 도구라기보다, 작은 코어를 가진 터미널 기반 LLM 작업대에 가깝습니다.

pi의 철학: 작게 시작하고 필요한 것만 붙인다

pi의 철학은 꽤 분명합니다. 다른 도구들이 기본 기능으로 넣는 것들을 pi는 일부러 기본값에서 뺍니다.

기본으로 넣지 않는 것	pi의 관점
MCP	외부 도구 연결 표준인 Model Context Protocol은 필요하면 extension으로 붙인다
Sub-agent	하위 에이전트 orchestration은 tmux로 여러 pi를 띄우거나 extension/package로 만든다
Permission popup	명령 실행 전 승인 UI는 컨테이너나 사용자 환경에 맞춘 confirmation flow로 해결한다
Plan mode	작업 계획 모드는 파일에 계획을 쓰거나 extension으로 만든다
Built-in TODO	내장 TODO 관리 대신 `TODO.md` 같은 일반 파일을 쓴다
Background bash	백그라운드 셸 실행 대신 tmux를 써서 관찰 가능하고 직접 개입할 수 있게 한다

처음 보면 “왜 없는 게 이렇게 많지?”라고 느낄 수 있습니다. 하지만 이 설계는 단순한 기능 부족이 아니라 비용에 대한 선택입니다.

MCP, 서브에이전트, 플랜 모드, 자동 TODO는 모두 강력합니다. 하지만 이 기능들이 코어에 들어가면 쓰지 않는 사용자도 그 설명과 절차의 일부를 매번 부담하게 됩니다. pi는 이 비용을 기본값으로 모두에게 부과하지 않겠다는 쪽에 가깝습니다.

pi가 잘 맞는 사람

pi는 모두에게 가장 편한 도구는 아닐 수 있습니다. 하지만 아래에 해당한다면 꽤 잘 맞을 가능성이 큽니다.

터미널 중심으로 개발한다.
셸 명령과 Git 같은 기본 개발 도구에 익숙하고, tmux나 git worktree 같은 터미널 도구도 필요하면 활용할 수 있다.
에이전트가 너무 많은 일을 자동으로 벌이는 것이 부담스럽다.
빠른 응답성과 작은 컨텍스트를 중요하게 본다.
기본 기능보다 내가 원하는 방식으로 조립하는 확장성을 선호한다.
프로젝트 규칙을 AGENTS.md 같은 텍스트 파일로 관리하고 싶다.

반대로 GUI 중심의 완성형 코딩 에이전트를 원하거나, MCP와 서브에이전트, 플랜 모드가 기본으로 켜져 있기를 기대한다면 pi가 처음에는 불편할 수 있습니다.

AI 코딩 도구와 함께 쓰는 프롬프트

Pi처럼 가벼운 에이전트 하네스를 쓸 때는 세션, 프로젝트 컨텍스트, package 설치 범위를 분명히 하는 것이 중요합니다. 중요: 네트워크 요청, sudo, 시스템 경로 접근이 필요한 package는 실행 전 별도 확인을 받으세요.

현재 프로젝트에서 pi를 실행해도 되는지 확인해줘.
프로젝트 폴더, AGENTS.md 같은 컨텍스트 파일, 현재 세션 목적을 먼저 설명하고 파일 수정은 하지 마.

이 pi package를 설치해도 되는지 검토해줘.
공식 출처, 설치 위치, 필요한 권한, 네트워크 요청 여부, 제거 방법을 먼저 설명하고, 설치 명령은 내가 허락하기 전에는 실행하지 마.

웹 탐색이나 고급 package를 붙일 때는 “민감 정보 접근 여부와 외부 요청이 발생하는지 먼저 알려줘”라고 덧붙이세요.

한 번에 정리

항목	내용
도구 성격	터미널 기반 minimal coding harness
핵심 방향	작은 코어, 필요한 기능만 확장
기본 작업 루프	파일 읽기, 수정, 셸 명령 실행, 결과 확인
확장 방식	prompt templates, skills, extensions, themes, pi packages
의도적으로 뺀 것	MCP 기본 탑재, sub-agent, plan mode, built-in TODO 등
잘 맞는 환경	터미널 중심 개발, 텍스트 기반 규칙 관리

다음 글에서는 pi를 설치하고 첫 세션을 실행하는 기본 흐름을 다룹니다.