mathbong
EN
수정됨 도구 Pi

[Pi 시리즈 3편] 세션과 프로젝트 컨텍스트 관리하기

#pi#session#agents-md#workflow
English version

이전 글에서는 pi를 설치하고 첫 세션을 시작하는 방법을 다뤘습니다. 이번 글에서는 pi를 하루 이상 실제 작업에 쓰기 위해 필요한 관리 기능을 정리합니다.

LLM 코딩 도구는 첫 실행보다 오래 쓰는 과정에서 차이가 납니다. 세션이 길어지고, 프로젝트 규칙이 늘어나고, 이전 대화가 현재 작업을 방해하기 시작하면 컨텍스트 관리가 중요해집니다.

이 글에서 할 것

  • pi 세션이 저장되는 방식 이해하기
  • 최근 세션 이어가기
  • 이전 세션 선택하기
  • /tree, /fork, /compact의 역할 구분하기
  • AGENTS.md와 CLAUDE.md로 프로젝트 규칙 전달하기
  • 무거운 세션을 피하는 운영 습관 정리하기

세션은 자동 저장된다

pi는 세션을 자동 저장합니다. 기본적으로 세션 파일은 ~/.pi/agent/sessions/ 아래에 작업 디렉터리별로 저장됩니다.

최근 세션을 이어서 열고 싶으면 다음 명령을 사용할 수 있습니다.

pi -c

저장된 세션을 골라서 열고 싶으면 다음 명령을 사용합니다.

pi -r

반대로 기록을 남기지 않는 일회성 작업을 하고 싶을 때는 세션 저장을 끌 수 있습니다.

pi --no-session

간단한 질문이나 빠른 요약 작업에는 --no-session이 오히려 깔끔합니다. 모든 대화를 저장하면 나중에 세션 목록이 불필요하게 복잡해질 수 있습니다.

세션이 길어질 때 생기는 문제

긴 세션은 편합니다. 이전 대화를 이어받을 수 있기 때문입니다. 하지만 너무 길어진 세션은 점점 무거워집니다.

대표적인 증상은 이렇습니다.

  • 예전에 논의한 파일이 현재 작업과 섞인다.
  • 모델이 오래된 결정을 아직 유효한 규칙처럼 사용한다.
  • 작은 수정에도 대답이 느려진다.
  • 같은 설명을 다시 요약하거나 반복한다.
  • 현재 작업과 무관한 도구 호출이 늘어난다.

이 문제는 pi만의 문제가 아닙니다. LLM 도구를 오래 쓰면 대부분 비슷한 현상이 생깁니다. pi에서는 이 문제를 /tree, /fork, /compact 같은 명시적인 세션 관리 기능으로 다룹니다.

/tree: 이전 지점으로 돌아가기

/tree는 현재 세션의 대화 트리를 보여주고, 이전 지점으로 돌아가 다른 방향으로 이어갈 수 있게 해줍니다.

/tree

예를 들어 어떤 리팩터링을 시도했는데 방향이 마음에 들지 않을 수 있습니다. 이때 전체 세션을 버리지 않고, 리팩터링을 시작하기 전 사용자 메시지로 돌아가 다른 방식으로 다시 진행할 수 있습니다.

이 기능은 특히 실험적인 작업에 유용합니다.

  • A 방식으로 수정해보기
  • 이전 지점으로 돌아가기
  • B 방식으로 다시 수정해보기
  • 두 결과를 비교하기

세션을 선형 로그로만 보는 것이 아니라, 가지를 가진 작업 기록으로 다룰 수 있다는 점이 장점입니다.

/fork: 특정 지점에서 새 세션 만들기

/fork는 이전 사용자 메시지를 기준으로 새 세션을 만드는 기능입니다.

/fork

/tree가 현재 세션 안에서 분기하는 느낌이라면, /fork는 특정 지점까지의 맥락을 복사해 새 세션 파일로 나누는 느낌에 가깝습니다.

다음 상황에서 유용합니다.

  • 현재 세션이 너무 길어졌을 때
  • 한 작업에서 다른 작업으로 갈라질 때
  • 같은 요구사항을 다른 모델이나 다른 전략으로 다시 시도하고 싶을 때
  • 기존 대화 기록은 보존하되 새 파일에서 가볍게 이어가고 싶을 때

큰 작업을 계속 한 세션에 밀어 넣기보다, 적당한 시점에 새 세션으로 나누면 응답 흐름이 훨씬 깔끔해집니다.

/compact: 긴 대화 압축하기

/compact는 길어진 대화를 압축해 컨텍스트를 정리하는 명령입니다.

/compact

선택적으로 압축 지시문을 붙일 수도 있습니다.

/compact 현재 구현 결정, 남은 TODO, 검증 명령만 남겨줘.

압축은 세션을 무조건 짧게 만드는 만능 기능은 아닙니다. 잘못 압축하면 세부 맥락이 빠질 수 있습니다. 그래서 중요한 작업에서는 압축 전에 다음 정보를 명시해두는 편이 좋습니다.

  • 최종 결정
  • 수정한 파일
  • 아직 남은 TODO
  • 실행한 검증 명령
  • 실패했지만 버린 접근

이렇게 정리해두면 /compact 이후에도 작업 흐름을 잃지 않을 가능성이 높아집니다.

프로젝트 규칙은 AGENTS.md로 전달한다

pi는 시작할 때 AGENTS.md 또는 CLAUDE.md를 읽어 프로젝트 규칙으로 사용합니다. 공식 문서 기준으로는 전역 파일, 현재 작업 디렉터리, 그리고 부모 디렉터리를 따라 발견한 파일을 함께 읽고, 발견된 규칙 파일들은 연결되어 모델에게 전달됩니다.

로드 대상은 다음과 같습니다.

  • 전역 규칙: ~/.pi/agent/AGENTS.md
  • 현재 작업 디렉터리와 부모 디렉터리의 AGENTS.md 또는 CLAUDE.md

예를 들어 블로그 프로젝트라면 다음과 같은 규칙을 AGENTS.md에 넣어둘 수 있습니다.

# Blog writing rules

- 새 블로그 글을 쓰기 전에 docs/content/blog-writing-guide.md를 읽는다.
- frontmatter에는 workflowStatus, readerReview, expertReview, humanReview, publishReady를 포함한다.
- 본문은 # H1을 쓰지 않고 ##부터 시작한다.
- 글을 크게 수정한 뒤에는 npm run check를 실행한다.

이런 규칙은 매번 프롬프트에 복사해서 붙여넣지 않아도 됩니다. 프로젝트 안에서 pi를 실행하면 자동으로 읽히기 때문입니다.

컨텍스트 파일을 끄고 싶을 때

항상 프로젝트 규칙이 필요한 것은 아닙니다. 아주 작은 파일 하나만 보고 싶거나, 프로젝트 규칙이 오히려 답변을 무겁게 만드는 상황도 있습니다.

그럴 때는 컨텍스트 파일 로딩을 끌 수 있습니다.

pi --no-context-files

이 옵션은 다음 상황에서 유용합니다.

  • 프로젝트 규칙과 무관한 일회성 질문
  • 특정 파일 하나만 독립적으로 검토하고 싶을 때
  • 전역 AGENTS.md가 너무 많은 지시를 포함하고 있을 때
  • 모델의 순수한 코드 해석만 보고 싶을 때

컨텍스트는 많을수록 항상 좋은 것이 아닙니다. 필요한 규칙만 남기는 것도 중요한 운영 습관입니다.

내가 쓰려는 기본 운영 원칙

pi를 계속 써본다면 다음 원칙으로 운영하려고 합니다.

  1. 작은 작업은 새 세션에서 시작한다.
    긴 세션에 모든 것을 쌓지 않습니다.

  2. 프로젝트 규칙은 AGENTS.md에 둔다.
    반복해서 말해야 하는 규칙은 프롬프트가 아니라 파일로 관리합니다.

  3. 큰 방향 전환은 /fork로 나눈다.
    한 세션 안에서 서로 다른 작업을 계속 섞지 않습니다.

  4. 긴 세션은 /compact 전에 요약 기준을 명시한다.
    “알아서 압축해줘”보다 “결정, TODO, 검증 결과만 남겨줘”가 안전합니다.

  5. 필요 없는 확장은 기본으로 켜지 않는다.
    pi를 쓰는 이유가 가벼움이라면, 확장도 필요한 것부터 하나씩 붙입니다.

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

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

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

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

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

한 번에 정리

기능 용도
pi -c 최근 세션 이어가기
pi -r 저장된 세션 고르기
pi --no-session 세션 저장 없이 일회성으로 실행
/tree 현재 세션 안에서 이전 지점으로 돌아가 분기
/fork 특정 지점에서 새 세션 만들기
/compact 긴 대화를 압축해 컨텍스트 정리
AGENTS.md 프로젝트 규칙을 자동으로 전달
--no-context-files 규칙 파일 로딩 끄기

pi의 핵심은 모든 기능을 기본으로 켜는 것이 아니라, 필요한 컨텍스트만 남겨 빠르게 반복하는 데 있습니다. 세션과 프로젝트 규칙을 가볍게 관리하면 이 철학을 실제 작업에서도 유지할 수 있습니다.

💬 댓글

이 글에 대한 의견을 남겨주세요

☰Pi 시리즈