코딩 에이전트가 고쳤다고 하는 것을 어떻게 검증하는지

몇 달 전 저는 Claude Code를 사용해 소프트웨어의 일부를 만들고 있었는데, 어느 순간 제가 손으로 확인해야 할 72가지 항목을 갖게 되었습니다. 에이전트는 작업을 마쳤고 테스트는 성공(green)했지만, 그 72가지 중 실제로 시도했던 것이 무엇이고 단순히 생각해 봤던 것은 무엇인지 전혀 알 수 없었습니다. 텍스트 파일의 몇 가지 메모, 머릿속에 있는 것들, 터미널에 적힌 몇 가지가 있었는데, 확실히 몇 개는 빠진 것 같았습니다.

그때 저는 코딩 에이전트와 작업하는 어려운 부분이 더 이상 코드를 작성하는 것이 아니라, 그들이 작성한 것이 실제로 작동하는지 아는 것임을 깨달았습니다.

에이전트를 사용하는 방법
제 워크플로우는 특별할 것 없지만, 나머지 이야기에서 중요합니다. 먼저 에이전트와 함께 계획(plan)을 세우고, 기능(features), 아키텍처, 제가 신경 쓰는 결정 사항들을 작성합니다. 그런 다음 작업을 검토하기에 충분히 작은 단계들로 나누도록 요청하고, 모든 단계마다 끝날 때가 아니라 그 단계의 일부로서 테스트를 명시적으로 작성하도록 요청합니다.

다음 단계로 넘어가기 전에 코드의 중요한 부분을 읽고 손으로 테스트합니다. 에이전트가 스스로 잘 처리하는 초기 부분들은 괜찮지만, 수동 테스트(manual testing)에서 문제가 발생하곤 했습니다.

성공적인 테스트만으로는 충분하지 않은 이유
자동화된 테스트는 에이전트가 발생할 것이라고 예상하는 것만을 확인합니다. 하지만 에이전트는 코드뿐만 아니라 테스트도 작성했기 때문에, 이들은 동일한 사각지대(blind spots)를 공유합니다.

테스트는 Safari에서는 페이지가 비어있지만 Chrome에서는 괜찮은 경우라든지, 오류 메시지는 표시되지만 폼(form)이 여전히 제출되는 경우라든지,

제가 원했던 것
저는 또 다른 테스트 프레임워크가 아니라 훨씬 더 간단한 것을 원했습니다. 에이전트는 자신이 무엇을 건드렸는지 알고 있으므로, 검증할 항목 목록을 작성하는 것이 에이전트의 역할이어야 합니다. 저는 이 목록을 테스트하면서, 종종 터미널이 아닌 휴대폰으로 확인하고 싶고, 그 결과는 복사-붙여넣기 없이도 에이전트가 조치할 수 있는 방식으로 에이전트에게 전달되어야 했습니다.

그래서 제가 이것을 만들었고, 이름은 palmtop입니다.

palmtop 작동 방식
에이전트에게 무언가를 수행하고 그 검증 항목들을 palmtop에 기록하도록 요청합니다:
implement phase 2 and put the checks on palmtop<br>에이전트는 작업을 수행한 다음, 무엇을 검증해야 하는지 체크리스트를 작성하며, 이 목록은 연결된 장치(휴대폰, 태블릿 또는 브라우저)에 실시간으로 표시되고 알림을 받게 됩니다.

사용자는 프로젝트의 각 항목을 테스트하고 다음과 같이 표시합니다: 작동하면 ✓, 안 되면 ✕와 함께 어떤 일이 일어났는지에 대한 짧은 메모를 남기거나, 더 많은 정보가 필요해서 확답할 수 없다면 ?를 표시합니다.

로그인 흐름에서 실제 예시:

• ✓ 비밀번호 오류 시 에러 메시지 표시
• ✕ 로그아웃 상태에서 /settings로 이동하면 /login으로 이동 → Safari에서 빈 페이지 표시
• ?

이것은 미리 보기(preview) 버전이라 솔직히 말씀드리자면: 메시지는 TLS를 통해 전송되지만, 아직 종단 간 암호화(end-to-end encrypted)는 아닙니다. 이것이 로드맵의 다음 주요 기능입니다. 그때까지는 체크리스트에 비밀 정보를 넣지 마세요.

사용해 보기 (Trying it)
Claude Code와 Codex에서는 별도의 설정 없이 작동하며, 셸 명령(shell commands)을 실행할 수 있는 다른 에이전트와도 사용 가능합니다. macOS, Linux 또는 WSL과 Node.js 22 이상 버전이 필요합니다.

curl -fsSL https://palmtop.mtwa.it/install.sh | bash

설치 프로그램은 에이전트를 설정한 다음 휴대폰을 페어링하기 위한 QR 코드를 보여줍니다. sudo를 사용하지 않으며, 실행하기 전에 스크립트를 읽어볼 수 있습니다.

지금까지 배운 점 (What I learned so far)
단순히 체크 사항들을 적는 것만으로도 절반의 가치를 얻지만, 목록이 있다는 사실 자체가 제가 무언가를 표시하기도 전에 더 신중하게 테스트하도록 만듭니다. 짧은 메모로 충분하며,