AI 에이전트에게 GitHub 배포나 API 연결을 맡기면 매번 처음 일하는 사람처럼 굽니다. 커넥터로 처리할 수 있는 일인데 토큰을 만들어 붙여 넣으라고 하고 화면이 바뀐 서비스의 예전 경로를 안내하고 이미 고친 권한 오류에서 또 같은 실패를 합니다. Portwright는 singandmong이 만든 오픈소스입니다. 에이전트가 외부 도구를 건드리기 직전에 그 도구에 대한 짧은 메모를 먼저 읽게 합니다. 지난번에 어떻게 연결했고 어디서 막혔는지 수첩에 남아 있으니, 에이전트가 같은 자리에서 다시 헤매지 않습니다.

Portwright 소개 이미지. 종이비행기가 검색, 실행, 분석을 지나는 경로 아래에 기억 레이어가 놓여 있다 — Portwright 소개 이미지. 출처: 저장소 assets, ChatGPT로 생성된 이미지. 확인일: 2026-10-07.

주요 기능

작업 전에 지난 절차와 실패 원인부터 확인합니다

단골 정비소의 정비 수첩과 같습니다. 정비사(에이전트)는 차(외부 도구)를 만지기 전에 수첩부터 엽니다. 수첩에는 세 가지 메모가 있습니다.

Procedure: 이 도구를 다루는 정답 절차입니다. 어디까지가 사람 몫인지도 적어 둡니다.
Lesson: 지난번에 무엇을 시도했고 진짜 원인이 무엇이었는지, 다음에는 무엇을 해야 하는지 적습니다.
Profile: 이 프로젝트에서 쓰는 계정과 저장소입니다.

에이전트가 portwright preflight github처럼 도구 이름을 넣어 preflight를 부르면 이 메모들이 한 번에 돌아옵니다. READY나 DERIVE REQUIRED 같은 상태와 절차 메모, 활성 교훈, 신선도 표시가 함께 나옵니다. 실행은 에이전트가 원래 쓰던 CLI, MCP, API로 직접 하고 Portwright는 조언만 합니다. OAuth 승인처럼 꼭 사람이 해야 하는 단계는 사람에게 넘깁니다.

처음 쓰는 도구도 메모가 쌓입니다

메모가 없는 도구를 만나면 DERIVE REQUIRED를 알리고 공식 문서를 바탕으로 초안을 만듭니다. 초안은 사람이 검토한 뒤 승격해 캐시에 넣습니다. 승격 전에는 비밀 패턴이 섞였는지, 원인이 확인되지 않은 교훈은 아닌지 검사합니다. 근거가 없으면 신선도를 fresh로 주지 않고 unknown으로 둡니다. 그럴듯해 보이는 것보다 정직한 표시를 택했습니다.

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

Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Oh My Pi, VS Code Copilot 등 8개 클라이언트를 지원합니다. 설치 전에 .bak 백업을 만들어 기존 설정을 지킵니다. 메모는 마크다운 파일이고 Python 표준 라이브러리만 쓰기 때문에 따로 깔 외부 패키지가 없습니다. OAuth 승인 화면을 누르고 짧은 명령을 따라 할 수 있다면 비개발자도 쓸 수 있습니다.

시작하기

준비물은 git, bash, Python 3.9 이상입니다.

PW="$HOME/tools/portwright"
git clone https://github.com/foxion37/portwright.git "$PW"
"$PW/bin/portwright" client install codex      # Client에 맞게 claude-code, cursor 등
"$PW/bin/portwright" check
"$PW/bin/portwright" client doctor codex
"$PW/bin/portwright" preflight github           # 캐시 HIT 예

2026-10-07 기준 최신 버전은 4.0.2입니다. 릴리스를 고정하려면 git -C "$PW" checkout v4.0.2를 실행하세요. 처음 켰을 때 신선도가 unknown으로 나오는 것은 정상입니다. 라이선스는 MIT입니다.

사용 전 확인하세요

macOS와 Linux를 지원하며 Windows에서는 검증하지 않았습니다. Python 3.9 미만은 지원하지 않습니다. Portwright는 조언용 등급만 매기고 실제 차단은 각 AI 클라이언트의 권한 프롬프트가 맡습니다. 메모에는 비밀번호나 토큰 값을 적지 말고 저장한 위치만 적으세요. 비밀 패턴 검사가 있지만 모든 비밀을 잡아내지는 못합니다. 다른 사람과 메모를 나누는 공유 허브는 초대제이고 실서버 검증이 끝나지 않은 선택 기능입니다. 유료 키가 필요한 선택 기능(JEV 판정)은 키가 없으면 confirm/unknown 같은 정해진 동작으로 돌아갑니다.

에이전트가 아무리 똑똑해져도 기억이 없으면 같은 실패를 되풀이합니다. 에이전트와 외부 서비스를 연결하다 같은 오류를 두 번 겪었다면, 아래 링크에서 GitHub 저장소로 가서 preflight 한 번으로 수첩을 시작해 보세요.

Portwright, AI 에이전트가 같은 실패를 반복하지 않게 하는 정비 수첩