Claude Code에서 OpenCode를 거쳐 pi까지 — AI 코딩 하네스를 점점 얇게 만든 기록

관련: AI 코딩 도구 지형도의 터미널 에이전트 비교에서 이어지는 개인 사용 기록이다.

AI 코딩 도구를 옮겨 다닌 흐름을 돌아보면 단순히 “더 좋은 도구”를 찾은 과정이 아니었다. 내 경우에는 다음 순서에 가까웠다.

Claude Code / Codex CLI
        ↓
OpenCode
        ↓
oh-my-opencode
        ↓
pi

처음에는 기능이 많은 완제품 에이전트가 편했다. 그런데 매일 쓰다 보니 실제로 반복해서 쓰는 것은 생각보다 작았다. 파일을 읽고, 검색하고, 필요한 부분만 수정하고, 테스트나 명령을 돌리고, 작업 규칙을 기억하는 정도였다. 결국 관심이 “무슨 기능이 더 있나”에서 “내 작업 흐름에 필요한 최소 실행 환경은 무엇인가”로 옮겨갔다.

이 글은 pi 사용법 전체 정리가 아니다. Claude Code·Codex CLI에서 OpenCode를 거쳐 pi까지 오면서 체감한 하네스(harness)의 두께 변화를 기록한다.

하네스란 무엇인가

여기서 하네스는 모델 자체가 아니라, 모델이 개발 작업을 수행하게 만드는 주변 실행 환경을 뜻한다.

모델
  └─ 하네스
      ├─ 파일 읽기
      ├─ 검색
      ├─ 명령 실행
      ├─ 파일 수정
      ├─ 권한·규칙
      ├─ 시스템 프롬프트
      └─ 작업 반복 루프

언어 모델은 그 자체로는 텍스트를 생성하는 엔진에 가깝다. 코딩 에이전트처럼 동작하려면 파일 시스템을 읽고, 셸 명령을 실행하고, 코드를 수정하고, 그 결과를 다시 보고 다음 행동을 결정해야 한다. 이 주변 장치와 실행 규칙의 묶음을 넓게 하네스라고 부를 수 있다.

하네스가 두꺼우면 처음 쓰기 편하다. 기본 명령, 권한 흐름, 메모리, MCP(Model Context Protocol, 외부 Tool·Resource 연결 Protocol), 서브에이전트 같은 기능이 이미 준비되어 있다. 반대로 하네스가 얇으면 처음에는 비어 보이지만, 필요한 것만 직접 붙일 수 있다.

하네스라는 말이 낯설다면 그냥 AI 작업 환경으로 읽어도 된다.

모델 = 머리
도구 = 손발(read, edit, bash 같은 실제 행동 능력)
규칙 = 행동 기준(AGENTS.md, CLAUDE.md 같은 문서)
흐름 = 작업 순서(skill, prompt template, hook)
하네스 = 이 모두를 묶은 작업 환경

따라서 하네스 구성의 가장 실질적인 부분은 AI agent에게 어떤 손발을 줄지 정하는 일이다. read를 줄지, edit을 허용할지, bash를 막을지, browser나 GitHub 도구를 추가할지 결정한다. 그 위에 규칙과 흐름을 얹으면 하나의 작업 환경이 된다.

1단계 — Claude Code와 Codex CLI: 완제품 에이전트

Claude Code나 Codex CLI는 처음 쓰기 좋다. 터미널에서 바로 시작할 수 있고, 파일을 읽고 수정하고, 명령을 실행하고, 세션을 이어가며, 제품이 정한 방식으로 권한과 컨텍스트를 관리한다.

이 단계에서 좋은 점은 명확하다.

• 기본 UX가 이미 갖춰져 있다.
• 프로젝트 규칙과 세션 관리 방식이 있다.
• 큰 작업을 에이전트에게 맡기는 감각을 빠르게 익힐 수 있다.
• MCP, 메모리, slash command 같은 주변 기능을 제품의 방식대로 사용할 수 있다.

하지만 어느 정도 익숙해지면 반대 방향의 질문이 생긴다.

내가 실제로 매일 쓰는 기능이 이만큼 많은가?

기능이 많다는 것은 장점이지만, 동시에 도구가 이미 정한 흐름을 따라간다는 뜻이기도 하다. 내가 원하는 것은 더 많은 버튼이 아니라, 반복 작업을 내 방식대로 줄이는 것이었다.

2단계 — OpenCode: provider와 model을 열어 둔다

OpenCode로 넘어오면 느낌이 달라진다. 특정 모델 생태계에 완전히 묶이기보다, provider와 model을 분리해서 고를 수 있다.

OpenCode
  └─ provider
      └─ model

이 구조는 도구 선택과 모델 선택을 분리해서 생각하게 만든다. 같은 Codex 계열 모델을 쓰더라도 공식 Codex CLI에서 돌리는 것과 OpenCode 하네스에서 돌리는 것은 다르다. 모델은 같아도 컨텍스트 구성, 도구 호출, 권한, TUI(Text-based User Interface, 터미널 사용자 인터페이스)의 감각이 달라지기 때문이다.

OpenCode에서 얻은 것은 자유도였다.

• 여러 provider를 붙일 수 있다.
• 모델을 바꿔가며 실험하기 쉽다.
• 오픈소스 도구라 설정과 동작을 더 직접적으로 볼 수 있다.
• Claude Code보다 내 쪽으로 끌어오는 느낌이 강하다.

다만 OpenCode 역시 사용자가 바로 쓸 수 있는 완성형 에이전트에 가깝다. 기본 하네스가 충분히 두껍고, 그 안에서 설정을 조정하는 방식이다.

3단계 — oh-my-opencode: 도구보다 내 워크플로가 중요해진다

그다음 단계는 OpenCode 자체보다 그 위에 얹은 개인 워크플로였다. 반복해서 쓰는 명령, 자주 요청하는 작업, 문서 작성 규칙, notes·blog·cheatsheet 같은 개인 루틴을 별도 레이어로 만들기 시작했다.

이 시점부터 관심사는 제품 기능 목록이 아니었다.

내가 매번 AI에게 반복해서 말하는 것은 무엇인가?

예를 들면 이런 것들이다.

• 문서를 고치기 전에 작성 규칙을 먼저 읽기
• 긴 파일은 전체 덮어쓰기보다 부분 수정 우선
• 수정 후 diff 확인
• 블로그 글은 매뉴얼이 아니라 비교·선택·경험 중심으로 쓰기
• 반복되는 기록은 notes나 cheatsheet로 보내기

이런 규칙은 특정 제품의 기능이라기보다 내 작업 방식이다. 그러면 자연스럽게 “도구를 잘 쓰는 법”에서 “내 작업 방식을 도구에 어떻게 이식할 것인가”로 질문이 바뀐다.

4단계 — pi: 거의 날것에 가까운 얇은 기반

pi를 처음 보면 오히려 없는 것이 눈에 띈다. pi 문서의 설계 원칙도 이 방향을 분명히 말한다. core는 작게 두고, workflow-specific behavior는 extensions, skills, prompt templates, packages로 밀어낸다. pi는 기본으로 MCP, sub-agent, permission popup, plan mode, todo, background bash를 두껍게 포함하지 않는다. 필요하면 extension이나 외부 도구로 구성하는 쪽이다.

처음에는 이것이 불친절해 보인다. 그런데 앞 단계들을 지나오면 이 얇음이 장점으로 보인다.

내가 실제로 자주 쓰는 기본 능력은 대략 이 정도다.

read  → 파일 읽기
bash  → rg, git, test 실행
edit  → 필요한 부분 수정
write → 새 파일 생성

여기에 pi는 프로젝트의 AGENTS.md나 CLAUDE.md를 컨텍스트 파일로 읽고, skill과 prompt template을 별도 자원으로 붙인다. 특히 skill은 ~/.agents/skills/나 프로젝트 .agents/skills/ 아래의 SKILL.md를 발견하고, 시작 시에는 이름과 설명만 시스템 컨텍스트에 넣는다. 실제 작업에 필요할 때 전체 skill을 읽는 구조다. 즉 모든 지침을 항상 밀어 넣기보다, 필요한 순간에 펼치는 progressive disclosure 방식이다.

내 환경에서는 여기에 pi-jev extension도 붙어 있었다. Jev는 pi core가 아니라 확장으로 들어온 보조 판단 도구에 가깝다. 애매한 분류, 선택, skill/tool 탐색처럼 “텍스트를 길게 생성”하기보다 빠르게 판정해야 하는 곳에 붙일 수 있다.

얇아진다는 것은 성능이 낮아진다는 뜻이 아니다

Claude Code / Codex CLI → OpenCode → pi로 갈수록 기본 제공 기능은 얇아진다. 하지만 이것이 곧 성능 저하를 뜻하지는 않는다.

두꺼운 하네스
  = 바로 쓰기 쉽다
  = 제품이 정한 흐름이 많다

얇은 하네스
  = 처음엔 직접 붙일 것이 많아 보인다
  = 필요한 것만 남기기 쉽다

나에게 중요한 차이는 속도만이 아니었다. 예측 가능성이 컸다. 파일을 읽고, 검색하고, 수정하고, 검증하는 단순 루프가 더 잘 보였다. 무엇이 기본 기능이고, 무엇이 내가 붙인 규칙인지 구분하기 쉬웠다.

물론 모두에게 pi가 맞는 것은 아니다.

• 제품이 알아서 많이 해주길 바라면 Claude Code나 Codex CLI가 편하다.
• 여러 provider와 model을 바꾸며 완성형 TUI를 쓰고 싶으면 OpenCode가 자연스럽다.
• 반복 작업을 직접 규칙·skill·template로 조립하고 싶으면 pi가 매력적이다.

구성과 커스텀은 어떻게 다른가

넓게 보면 하네스를 구성하는 것도 커스텀의 일부다. 다만 뉘앙스를 나누면 다음과 같다.

구성
  → 어떤 부품을 붙일지 정한다
  → 도구, skill, extension, prompt template, 권한

커스텀
  → 붙인 부품이 내 방식대로 움직이게 조정한다
  → 문체, 작업 규칙, 실행 순서, 안전장치

예를 들어 read, edit, bash만 허용하고 write를 빼거나 pi-jev extension을 붙이는 것은 구성에 가깝다. 반면 “긴 파일은 전체 덮어쓰지 말라”, “블로그 글은 작성 규칙을 먼저 읽으라”, “수정 후 diff를 확인하라”는 것은 커스텀에 가깝다.

실제 대화에서는 둘을 엄격히 나누지 않는다. 누군가 “하네스를 구성했다”고 말하면 대개 도구를 고르고, 규칙을 쓰고, 반복 흐름을 만들고, 필요한 확장을 붙였다는 뜻이다. 큰 범주로는 전부 커스텀이고, 그중 어떤 손발과 작업 환경을 줄지 조립하는 부분을 구성이라고 부르는 셈이다.

pi에서 붙인다는 것은 무엇인가

처음 pi를 쓰면 “뭘 붙이라는 거지?”라는 질문이 든다. 답은 거창하지 않다. 내가 매번 반복해서 말하던 것을 하나씩 밖으로 빼는 것이다.

반복 지시
  → AGENTS.md / APPEND_SYSTEM.md

반복 프롬프트
  → prompt template

작업 단위 지식과 절차
  → skill

외부 시스템 호출
  → extension / custom tool

예를 들어 블로그 작업에서는 다음 규칙이 하네스의 일부가 된다.

• 글 작성 전 블로그 작성 규칙을 읽는다.
• 기존 글과 중복되는지 먼저 찾는다.
• 매뉴얼성 명령어 나열은 devkit cheatsheet로 보내고, 블로그에는 비교·선택·경험을 남긴다.
• 공개 글에서는 개인 대화와 내부 맥락을 일반화한다.

이것은 특정 모델의 지능 문제가 아니라 실행 환경의 문제다. 같은 모델도 어떤 하네스에서 도는지에 따라 작업 감각이 달라진다.

날것의 pi 위에 얹은 작은 레이어

pi 생태계에는 아직 oh-my-zsh나 oh-my-opencode처럼 사실상 표준에 가까운 oh-my-pi가 굳어져 있지는 않다. 대신 pi package 단위로 작은 개선들이 흩어져 있다. 이 점도 pi답다. 하나의 큰 배포판을 설치한다기보다, 필요한 extension과 prompt template을 골라 얹는 방식이다.

내가 원한 것은 기능을 많이 늘리는 것이 아니라, pi의 날것 느낌을 줄이고 토큰을 덜 쓰는 기본값을 만드는 것이었다. 그래서 무거운 workflow package보다 먼저 다음 조합을 붙였다.

레이어	역할
pi-spark	editor와 footer를 정리해 TUI를 덜 산만하게 만든다.
@zigai/pi-response-renderer	assistant 응답 표시를 더 compact하게 만든다.
@eko24ive/pi-ask	애매한 선택을 추측하지 않고 구조화된 질문으로 되돌릴 수 있게 한다.
AGENTS.md	“짧게 답하기”, “한국어 기본”, “불필요한 배경 설명 금지” 같은 내 기본 작업 규칙을 고정한다.
prompt template	/fix, /review, /commit처럼 반복 요청을 짧은 명령으로 꺼낸다.

여기서 중요한 것은 package 자체보다 경계다. pi-spark의 자동 recap이나 자동 title처럼 편하지만 LLM 호출을 추가로 만들 수 있는 기능은 꺼 둘 수 있다. 반대로 UI를 정리하거나 응답 렌더링만 바꾸는 기능은 작업 흐름을 크게 흔들지 않으면서 체감 품질을 올린다.

결국 내가 만든 것은 거창한 배포판이 아니라 작은 preset에 가깝다.

pi core
  ├─ package: TUI와 응답 표시를 다듬는다
  ├─ ask tool: 애매할 때 질문하게 한다
  ├─ AGENTS.md: 기본 행동 규칙을 고정한다
  └─ prompts: 반복 요청을 짧게 만든다

이 정도만 얹어도 pi는 “빠르지만 날것”에서 “얇지만 내 작업 방식이 붙은 하네스”에 가까워진다. 완제품 에이전트처럼 모든 것을 미리 갖추지는 않지만, 반복해서 말하던 규칙을 밖으로 빼고 필요한 패키지만 고르면 매일 쓰는 감각은 꽤 달라진다.

plan mode도 하네스에 붙이는 기능이다

OpenCode처럼 plan mode를 별도 흐름으로 쓰고 싶다면, pi에서는 그것도 core 기능이 아니라 extension으로 붙인다. pi README는 기본값에서 sub agent와 plan mode를 일부러 제외한다고 설명한다. 대신 examples 아래에 plan-mode extension이 있고, 이를 전역 extension 위치에 두면 /plan 명령으로 사용할 수 있다.

~/.pi/agent/extensions/plan-mode/
  ├─ index.ts
  ├─ utils.ts
  └─ README.md

이 extension이 하는 일은 모델의 지능을 바꾸는 것이 아니다. 모델 주변의 행동 환경을 바꾼다.

평소 모드
  → read / bash / edit / write 사용

plan mode
  → edit / write 차단
  → bash는 읽기 중심 명령만 허용
  → 먼저 Plan: 형식의 번호 목록을 만들게 함

실행 모드
  → 도구 제한을 풀고 계획을 순서대로 실행
  → [DONE:n] 표시로 진행 상황 추적

그래서 plan mode는 모델 기능이라기보다 하네스 기능에 가깝다. Claude Code나 OpenCode에서 제품이 기본으로 제공하는 흐름을 pi에서는 extension으로 조립하는 셈이다.

이 지점에서 pi의 성격이 더 분명해진다. pi는 “plan mode가 없는 도구”라기보다, plan mode까지도 사용자가 하네스의 일부로 붙일 수 있게 둔 도구에 가깝다. 필요 없으면 비워 두고, 필요해지면 붙인다. 내 경우에는 실수로 파일을 고치기 전에 먼저 읽고 계획하는 흐름이 필요해졌고, 그래서 plan-mode extension을 전역 extension으로 올렸다.

결론 — 더 많은 기능보다 더 얇은 경계

이동 과정을 한 줄로 줄이면 이렇다.

완제품 에이전트를 쓰다가,
내가 실제로 쓰는 최소 루프를 발견했고,
그 루프를 직접 조립할 수 있는 얇은 기반으로 이동했다.

Claude Code와 Codex CLI는 좋은 완제품 에이전트다. OpenCode는 provider와 model의 자유도를 열어 준다. oh-my-opencode 같은 개인 레이어를 얹기 시작하면, 결국 관심은 제품 자체보다 내 작업 방식으로 이동한다. pi는 그 지점에서 재미있다. 처음부터 많은 것을 제공하기보다, 필요한 것만 붙일 수 있게 비워 둔다.

그래서 pi는 “더 강한 Claude Code”라기보다, 직접 조립하는 에이전트 셸에 가깝다. 불편함이 생길 때마다 하나씩 붙이면 된다. 매번 반복해서 말하는 것이 생겼다면, 그것이 다음에 하네스에 넣을 후보다.