본문으로 건너뛰기
Portwright
GitHub

AI 에이전트를 위한 도구 사용 기억 레이어

에이전트는 도구 쓰는 법을 잊습니다. Portwright가 수첩에 남겨 둡니다.

Portwright는 에이전트가 도구를 만지기 전에 그 도구에 대한 짧은 메모부터 읽게 합니다. 지금 맞는 절차, 지난번에 실패한 이유, 사람이 해야 하는 단계가 적혀 있습니다. Markdown 파일과 Python 표준 라이브러리만 씁니다. git clone 한 번이면 됩니다.

macOS, Linux 
PW="$HOME/tools/portwright"
git clone https://github.com/foxion37/portwright.git "$PW"
"$PW/bin/portwright" client install codex
"$PW/bin/portwright" check
"$PW/bin/portwright" preflight github

git, bash, Python 3.9 이상이 필요합니다. codex 자리에는 claude-code, cursor처럼 쓰는 클라이언트 이름을 넣으세요.

GitHub에서 보기 소개 글 읽기
버전
v4.0.2
라이선스
MIT, 무료
실행 환경
macOS, Linux
필요한 것
git, bash, Python 3.9 이상

똑똑한 에이전트도 같은 실수를 반복합니다.

에이전트에게 GitHub 배포나 API 연결을 맡기면 매번 처음 일하는 사람처럼 굽니다. 커넥터로 될 일인데도 토큰을 붙여 넣으라고 하고 화면이 바뀐 서비스의 예전 경로를 안내하며 이미 고친 권한 오류에서 또 막힙니다. 기억이 없으면 같은 실패를 두 번 합니다.

preflight

도구를 만지기 전에 한 번 확인합니다.

에이전트가 도구 이름을 넣어 portwright preflight를 실행하면 필요한 내용이 한꺼번에 돌아옵니다. READY나 DERIVE REQUIRED 같은 상태, 절차 메모, 지금 유효한 교훈, 신선도 표시입니다. 실제 작업은 에이전트가 원래 쓰던 CLI, MCP, API로 직접 합니다. Portwright는 조언만 하고 OAuth 승인처럼 사람이 해야 하는 단계는 사람에게 넘깁니다.

공개 저장소를 막 받은 상태
$ "$PW/bin/portwright" preflight github
READY: github
Profile: (none) no profiles defined
Procedure: services/github.md
Freshness: unknown -> verify-required (no evidence supplied (rule 3))
Tier: confirm
Active Lessons: 3

메모 세 가지

Procedure, Lesson, Profile.

짧은 Markdown 메모 세 가지가 일을 합니다.

  • Procedure: 지금 맞는 절차와 그 가운데 사람만 할 수 있는 단계.
  • Lesson: 무엇을 시도했는지, 확인된 원인, 고친 방법.
  • Profile: 이 프로젝트가 쓰는 GitHub 계정, 비밀값 출처, 데이터베이스.
Portwright 표지. 종이비행기가 검색, 실행, 분석을 지나는 경로 아래에 기억 레이어가 놓여 있다
portwright 저장소의 표지 이미지(ChatGPT로 생성).

스스로 쌓이는 메모

처음 쓰는 도구에도 메모가 생깁니다.

도구 500개를 미리 적어 둔 목록은 없습니다. 메모가 없는 도구를 만나면 Portwright가 DERIVE REQUIRED를 알리고 에이전트가 공식 문서를 보고 지금 맞는 절차의 초안을 씁니다. 초안은 비밀값이 섞였는지, 원인이 확인되지 않은 교훈은 아닌지 검사한 뒤 사람이 검토해야 캐시에 들어갑니다.

preflight가 알려 주는 것
  1. READY메모가 있습니다. 읽고 나서 실행합니다
  2. DERIVE REQUIRED메모가 없습니다. 공식 문서로 초안을 씁니다
  3. fresh | stale | unknown신선도. 근거가 없으면 fresh가 되지 않습니다
  4. auto | confirm | forbid조언 등급. 모르면 confirm으로 둡니다

정직함을 지키는 약속 세 가지.

그리고 켜 두어도 안심할 수 있게 챙긴 것들입니다.

  1. 신선도를 부풀리지 않습니다

    fresh에는 근거가 필요합니다. 근거가 없으면 unknown과 "먼저 확인"을 알리며 unknown을 fresh로 올리지 않습니다.

  2. 등급은 조언이지 차단이 아닙니다

    auto, confirm, forbid 가운데 하나를 알려 주는 데서 멈춥니다. 실제로 막는 것은 클라이언트의 권한 확인 창입니다.

  3. 캐시는 스스로 채워집니다

    누가 미리 적어 둔 지식이 아니라 필요할 때 쌓인 지식입니다.

  4. 프로필 라우터

    프로필이 프로젝트 폴더마다 GitHub 계정, 환경 변수 출처, 데이터베이스를 묶어 두어 preflight가 맞는 계정 기준으로 답합니다.

  5. 안전한 업데이트

    portwright update는 git pull --ff-only로 새 메모를 받고 오래된 메모는 다시 점검합니다.

  6. 백업 먼저

    클라이언트 설치는 기존 설정을 건드리기 전에 .bak 백업부터 만듭니다.

지금 쓰는 에이전트에 그대로 붙습니다.

아래를 포함해 클라이언트 8개를 지원합니다.

사용 전 확인하세요

한 번 설치해 두면 같은 실패를 반복하지 않습니다.

저장소를 받고 클라이언트를 연결한 뒤, 다음 도구를 쓰기 전에 preflight를 실행하세요.

GitHub에서 보기 소개 글 읽기