AI 도구 스튜디오 프로젝트

Portwright, AI 에이전트가 도구를 만지기 전에 메모부터 읽게 하는 도구

지난번에 어떻게 연결했고 어디서 실패했는지 기억하게 하는 로컬 기억 레이어. 마크다운 파일과 Python 표준 라이브러리만으로 동작한다.

글 SingandMong Studio 2026-10-07 연결된 노트 0개
내 관점

에이전트의 같은 실수는 더 똑똑한 모델보다 지난 실패를 적어 둔 수첩이 막는다

AI 에이전트에게 GitHub 배포나 API 연결을 시키면 매번 처음 일하는 사람처럼 행동합니다. 커넥터로 처리할 수 있는데 토큰을 만들어 붙여 넣으라 하고 화면이 바뀐 서비스의 예전 경로를 안내하고 이미 고친 권한 오류에서 같은 실패를 반복합니다. Portwright는 SingandMong Studio가 만든 오픈소스로, 에이전트가 외부 도구를 건드리기 직전에 그 도구에 대한 짧은 메모를 먼저 읽게 만듭니다.

한 줄 판단 Claude Code, Codex, Cursor 같은 AI 에이전트로 외부 서비스를 붙이는 작업을 반복하는 사람에게 맞습니다. macOS와 Linux만 지원하고 설치는 git clone과 짧은 명령 몇 개면 끝납니다. 잘 맞는 사람: 같은 도구 연결 실패를 에이전트와 함께 두 번 이상 겪어 본 사람. 비개발자도 OAuth 승인 화면을 누르고 짧은 명령을 따라 할 수 있으면 쓸 수 있습니다. 먼저 볼 제약: 도구를 대신 실행하거나 차단해 주지 않습니다. Windows는 검증하지 않았고 공유 허브는 아직 초대제입니다. 검증 상태: 저장소 기준 공식 자료 분석 확인일: 2026-10-07

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

어떤 일을 줄여주나

단골 정비소의 정비 수첩을 생각하면 됩니다. 정비사(에이전트)가 차(외부 도구)를 만지기 전에 수첩부터 폅니다. 수첩에는 세 가지 메모가 있습니다.

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

에이전트가 도구를 쓰기 전에 preflight를 부르면 이 메모들이 한 번에 돌아옵니다. 수첩이 정비를 대신하지는 않듯, Portwright도 실행은 에이전트가 기존 도구로 직접 합니다. 대신 “지난번에 이래서 실패했다”를 다시 헤매지 않게 해 줍니다.

AI와 함께 어디까지 할 수 있나

  • 입력: 에이전트가 쓰려는 도구 이름(예: portwright preflight github)
  • 사람이 고치는 곳: 메모 초안을 검토하고 승격하는 단계. OAuth 승인처럼 꼭 사람이 해야 하는 단계도 사람에게 넘깁니다.
  • 결과: READY나 DERIVE REQUIRED 같은 상태, 절차 메모, 활성 교훈, 신선도 표시
  • 넘겨줄 수 있는 곳: 없습니다. 조언이 끝나면 에이전트가 원래 쓰던 CLI, MCP, API로 직접 실행합니다.

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

설치와 시작

준비물은 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를 씁니다. Claude Code, Codex, Gemini CLI, Cursor, OpenCode, Oh My Pi, VS Code Copilot 등 8개 클라이언트를 지원하고 설치 전에 .bak 백업을 만듭니다. 처음 켰을 때 신선도가 unknown으로 나오는 건 오류가 아니라 정상입니다.

아직 확인하지 못한 점과 제약

  • 차단 장치가 아닙니다. 조언용 등급을 줄 뿐 실제 차단은 각 AI 클라이언트의 권한 프롬프트가 합니다. 게이트웨이나 정책 엔진을 목표로 하지 않는다고 스스로 밝힙니다.
  • 공유 허브는 검증이 끝나지 않았습니다. 다른 사람의 메모를 나누는 공개 허브는 초대제이고 실서버 검증이 완료되지 않아 선택 기능입니다.
  • Windows는 미검증이고 Python 3.9 미만은 지원하지 않습니다.
  • 메모에 비밀번호나 토큰 값을 적지 말고 어디에 저장했는지만 적으라고 안내합니다. 비밀 패턴 검사가 있지만 모든 비밀을 잡아내지는 못합니다.
  • 유료 키가 필요한 선택 기능(JEV 판정)이 있지만 키가 없으면 confirm/unknown 같은 정해진 동작으로 돌아갑니다. 라이선스는 MIT이며 소개 이미지는 ChatGPT로 생성했습니다.

마무리

에이전트가 똑똑해져도 기억이 없으면 같은 실패를 반복하는데 Portwright는 그 기억을 마크다운 파일로 남기는 작은 도구입니다. 에이전트와 외부 서비스 연결에서 같은 오류를 두 번 겪었다면 preflight 한 번으로 수첩을 시작해 보세요.

작성과 검토

  • 작성: SingandMong Studio
  • AI 사용: 조사와 초안 작성에 사용, 사람이 검토
  • 마지막 확인: 2026-10-07

근거

  1. Portwright 한국어 README: 정의, 푸는 문제, preflight 예시, 하지 않는 것
  2. 설치 안내: 요구 사항, 설치 명령, 클라이언트별 설치 표
  3. CHANGELOG: 1.1.0(2026-06-12)~4.0.2(2026-10-03) 이력

수정 기록

  • 2026-10-07 초안 작성
  • 2026-10-07 AI 슬롭 검사와 humanize-korean 윤문, 줄표와 가운데 점 정리