Claude Code에게 앱 하나를 그냥 맡기면, 긴 작업 중간에 규칙을 잊거나 하면 안 되는 일을 하기도 합니다. 그래서 클로드 주변에 하네스를 둡니다. 말에게 채우는 마구처럼, 에이전트가 정한 길로 일하게 만드는 장치들입니다.
이번에는 하네스를 하나가 아니라 네 겹으로 한 앱에 얹었습니다. 만든 앱은 서울 공영주차장 빈자리를 3D 지도로 보여 주는 휴대폰 웹 앱입니다. 주차장마다 빈자리만큼 기둥이 솟고, 라벨의 숫자가 빈자리 수입니다.
이 글에서는 다음을 차례로 봅니다.
- 준비물과 데이터: 인증키 하나로 두 데이터셋
- 디자인 하네스를 빈 폴더에서 직접 만들기
- 디자인 하네스로 기획부터 3D 지도 앱까지
- 일반 하네스 쌓기: 규칙, 테스트, 훅, 권한, CI
- pstack 얹고 겹치는 것 덜기
- TLA+ 형식 검증으로 새로고침 순서 버그 찾기
- 네 도구가 부딪힌 곳과 해결
- 직접 재 보기: 하네스만 vs 형식 검증
숫자 읽는 법. [공식 문서] 는 만든 쪽이 직접 낸 자료, [직접 측정] 은 이번 실습에서 저희가 직접 돌려서 나온 숫자입니다. 테스트 개수나 걸린 시간은 그날 그 코드 기준이라, 같은 프롬프트로 다시 해도 조금씩 달라질 수 있습니다.
1. 준비물과 데이터
필요한 건 다섯 가지입니다.
- Claude Code: 모든 장면에서 터미널로 일을 시킵니다.
- Node.js 20 이상: 앱의 작은 서버, 테스트, 디자인 하네스 명령이 모두 노드로 돕니다.
- 서울 열린데이터광장 인증키: 무료로 발급받습니다.
- 피그마 데스크톱 앱: 무료 플랜이면 충분합니다.
- 자바: 형식 검사기 TLC를 돌릴 때만 필요합니다.
데이터는 두 개를 씁니다. [공식 문서]
- 서울시 시영주차장 실시간 주차대수 정보(OA-21709), 서비스 이름
GetParkingInfo. 주차장마다 지금 몇 대가 서 있는지 줍니다. - 서울시 공영주차장 안내 정보(OA-13122), 서비스 이름
GetParkInfo. 위치·요금·운영시간이 들어 있습니다. 3D 지도에 기둥을 세우려면 위치가 필요해서 같이 씁니다.
좋은 점은 인증키 하나로 두 데이터셋을 다 부를 수 있다는 겁니다. 키는 프로젝트 폴더의 .env에 SEOUL_OPENAPI_KEY=로 넣고, .gitignore로 깃에 올리지 않습니다. 화면, 채팅, 코드에 키를 붙여 넣지 않는 게 원칙입니다.
피그마에는 figma-run이라는 작은 명령으로 그립니다. 내 컴퓨터에서만 열리는 중계 서버(127.0.0.1의 3055번)를 거쳐, 피그마 앱에 켜 둔 Talk to Figma 플러그인으로 그릴 코드를 보냅니다. 바탕은 오픈소스 cursor-talk-to-figma-mcp이고, 코드를 실행하는 명령 하나만 더했습니다. 공식 피그마 도구를 쓰지 않은 건 무료 플랜에서 한 달에 부를 수 있는 횟수가 적기 때문입니다.
2. 디자인 하네스를 빈 폴더에서 직접 만들기
디자인 하네스는 화면을 바로 만들지 않고, 디자이너가 일하는 순서를 그대로 따라가게 하는 장치입니다. PRD(무엇을 만들지 적은 문서) → 리서치 → 화면 구조 → 와이어프레임 → 디자인 시스템 → 피그마 → 검증 → 핸드오프, 이렇게 여덟 단계입니다. 중간에 사람이 승인해야 다음 단계로 갑니다.
다섯 번에 나눠 부탁해서 만들었습니다. [직접 측정]
| 순서 | 만든 것 | 테스트 |
|---|---|---|
| ① 설계 문서 | 165줄짜리 HARNESS-DESIGN.md. 단계마다 생기는 파일, 넘어가는 조건, 사람 승인 여부를 표로 | – |
| ② 판정과 승인 | check(지금 어느 단계인지 판정), approve(사람 승인 기록) | – |
| ③ 단계별 도구 | 레퍼런스 캡처, 와이어프레임, design-md, lint:web, 리뷰, 핸드오프 | 69개 통과 |
| ④ 에이전트와 스킬 | 승인 차단 훅 → 에이전트 다섯(리서치·화면 구조·디자인 시스템·피그마·비평가) → design-flow 스킬 | 75개 통과 |
| ⑤ 피그마 안전장치 | 피그마 쓰기 전 문지기 훅(figma-guard), 쓴 뒤 노드 내보내기 알림, 답을 끝낼 때 check를 돌리는 Stop 훅, lint:figma, 플러그인으로 묶기 | 92개 통과 |
설계의 중심 원칙은 두 줄입니다.
- AI는 스스로 승인할 수 없다. 승인 명령은 사람이 직접 칩니다. 사용자가 "승인해 줘"라고 말해도 클로드는 대신 실행하지 않고, 직접 입력하라고 다시 안내합니다.
- 승인할 때 파일 지문(해시)을 남긴다. 해시는 파일 내용으로 만든 지문이라 글자 하나만 바뀌어도 달라집니다. 승인한 뒤 파일이 바뀌면 그 승인은 무효가 됩니다. 지문은
approvals.json에 남습니다.
디자인 시스템 단계에서는 파일 세 개가 생깁니다. tokens.json(색·간격·글자 크기), components.json(부품과 상태), copy.json(화면 문구와 쓰면 안 되는 말). 사람과 AI가 한 번에 읽기 쉽게 이 셋을 DESIGN.md 형식의 문서 하나로 옮기는 게 design-md 명령입니다. [공식 문서] DESIGN.md는 구글 랩스가 공개한, 코딩 에이전트에게 디자인 시스템을 설명하는 형식입니다.
검사도 두 쪽에 겁니다.
lint:web: 완성된 웹 화면을 검사합니다. 토큰에 없는 색, 정해진 크기 밖의 글자, 손가락으로 누르기 어려운 44픽셀보다 작은 버튼, 쓰면 안 되는 문구를 찾습니다.lint:figma: 피그마에 그린 화면을 노드 목록으로 꺼내, 색이 변수에 연결됐는지, 명도 대비가 충분한지, 레이어 이름이 "프레임 12" 같은 기본값으로 남지 않았는지 봅니다.
만드는 과정에서 눈여겨볼 장면도 있었습니다.
- 테스트 하나가 실패하자, 클로드가 코드 대신 테스트의 기대값이 틀렸다(빈 상태를 빠뜨림)고 판단하고 그쪽을 고쳤습니다.
- 테스트가 다 통과했는데도 실제 크롬으로 끝까지 돌려 보고, 그린 와이어프레임을 열어 여백과 밑줄이 어긋난 걸 찾아 고쳤습니다.
- 스스로 한계를 적었습니다.
lint:web은 소스만 읽어서 외부 CSS로 정해지는 버튼 크기는 못 잡고, 승인 차단 훅은 명령을 글자로만 봐서 일부러 하는 우회까지는 막지 못한다고요.
3. 디자인 하네스로 기획부터 3D 지도 앱까지
빈 프로젝트 폴더(.env 하나뿐)에 디자인 하네스 플러그인을 두 줄로 설치하고, 앱을 만들어 달라고 부탁했습니다. 이 단계에서는 같은 설계로 더 오래 다듬은 완성판 하네스를 썼습니다. 직접 만들면 매번 조금씩 다르게 나와서, 따라 하는 사람이 실습 저장소와 똑같은 명령·파일을 보게 하려는 겁니다.
클로드는 하네스 순서대로 움직였습니다. [직접 측정]
- 리서치: 비슷한 서비스 여덟 곳을 캡처하고, 레퍼런스마다 본 것·가져올 점·피할 점을 적었습니다. 한 곳은 방화벽에 막혔는데, 우회하지 않고 "수집 한계"에 적었습니다. 캡처·관찰·가져올 점이 다 채워진 레퍼런스가 세 개는 있어야
check가 다음 단계로 보내 줍니다. - 와이어프레임: 지도·목록·상세·검색 네 화면. 여기서 멈추고 사람 승인을 기다렸습니다.
- 디자인 시스템: 토큰 134개, 부품 24개. 기둥에만 색을 쓰고 나머지는 무채색으로 두어 지도 위에서 기둥이 먼저 보이게 했습니다.
사람이 정한 건 기둥 높이 규칙 하나였습니다. 빈자리 수에 그대로 비례하면 큰 주차장 하나 때문에 작은 주차장 기둥이 바닥에 붙습니다. 그래서 제곱근 비율 + 최소 높이로 정했습니다. 제곱근은 큰 수는 덜 크게, 작은 수는 덜 작게 눌러 줍니다(100의 제곱근은 10, 4의 제곱근은 2). 실제 데이터로 비교하니 이렇게 바뀌었습니다. [직접 측정]
| 빈자리 | 그대로 비례 | 제곱근 + 최소 높이 |
|---|---|---|
| 1067 (세종로, 가장 많음) | 300px | 300px |
| 23 (중간쯤) | 6px | 65px |
| 5 | 1px | 43px |
높이 순서는 빈자리 순서 그대로라서 "많은 곳이 더 높다"는 그대로 지켜집니다.
그다음 피그마에 화면 23장을 그렸습니다. 불러오는 중, 오류, 결과 없음, 위치 권한 거부 같은 상태 화면까지요. 다 그리면 바로 승인으로 가지 않고, 그린 에이전트가 아니라 새 맥락의 비평 에이전트가 처음부터 봅니다. 첫 비평은 하이 2개, 미디엄 10개, 닛 6개였습니다. [직접 측정]
- 지도 라벨이 어느 기둥 것인지 헷갈린다 → 라벨과 기둥을 잇는 지시선을 넣음
- 기둥 높이 기준이 화면마다 바뀐다 → 서울 전체 최댓값(1067)으로 고정
고칠 내용에 디자인 시스템 변경이 들어가자, 클로드는 시스템 재승인 단계에서 한 번 멈췄습니다. 하네스가 정한 승인 순서를 건너뛰지 않은 겁니다. 다시 그린 뒤 두 번째 비평에서는 크게 막히는 문제가 없었고, 사람 검토 점수는 24점 만점에 19점이 기록됐습니다. 공휴일 운영시간이 0시~0시로 적힌 62곳처럼 원자료가 뜻을 밝히지 않은 값은 지어내지 않고 "시간 정보 없음"으로 두고 사람에게 물었습니다.
마지막으로 핸드오프 문서를 바탕으로 index.html 한 파일짜리 앱을 만들었습니다. 지도는 MapLibre GL JS와 OpenFreeMap으로 그립니다. 앱 코드에는 사람이 정한 높이 규칙이 한 줄로 들어갔습니다. 최소 높이 + 남은 높이 × √(빈자리 ÷ 서울 전체 최대 빈자리).
훅은 정해 둔 도구 이름에만 걸린다
이 단계에서 배운 가장 중요한 점입니다. 디자인 하네스의 피그마 문지기(figma-guard 훅)는 hooks.json에서 피그마 도구 이름에만 걸려 있습니다. 그런데 우리가 쓴 figma-run은 피그마 도구가 아니라 Bash로 실행하는 터미널 명령이라, 문지기가 없는 옆길이었습니다.
클로드는 이걸 스스로 짚고, 문지기가 하던 일 세 가지를 피그마 담당 에이전트가 직접 했습니다. 쓰기 전마다 열린 피그마 파일 이름을 확인하고, figma.json의 마지막 쓰기 시각을 직접 적고, 노드를 내보냈습니다. 검사 스크립트 원본은 건드리지 않았습니다.
정리하면, 훅은 실제로 쓰는 길에 걸어야 합니다. 같은 일을 다른 길로 하면 훅이 보지 못합니다.
4. 일반 하네스 쌓기
일반 하네스의 장치는 두 가지로 나눌 수 있습니다.
- 알려 주기:
CLAUDE.md, 경로 규칙, 스킬. 클로드가 읽고 따르는 것들입니다. - 확인하기: 훅, 권한, CI. 따랐는지를 기계가 직접 확인합니다.
알려 주기만 있으면 긴 작업 중에 잊을 수 있습니다. 그래서 중요한 규칙은 확인하기 쪽에도 하나씩 걸어 둡니다.
규칙. 공식 문서 CLAUDE.md는 클로드를 켤 때마다 통째로 읽히고, 경로 규칙은 맨 위 paths에 적은 파일을 만질 때만 읽힙니다. 그래서 CLAUDE.md에는 늘 지킬 것만 짧게(숫자는 실제 응답에서만, 인증키는 커밋하지 않기, 빈자리 옆엔 늘 기준 시각) 두고, 화면·데이터·디자인 산출물 규칙은 경로 규칙 세 개로 나눴습니다. 규칙은 "코드를 깔끔하게"처럼 확인할 수 없는 말 대신, "좌표가 없으면 0으로 채우지 않는다"처럼 지켰는지 볼 수 있는 문장으로 씁니다. 그래야 나중에 테스트나 훅으로 바꿀 수 있습니다.
테스트와 변형 시험. [직접 측정] 노드 기본 테스트 도구로 꼭 필요한 테스트 13개를 쓰고, 코드를 일부러 하나씩 망가뜨려 테스트가 잡는지 봤습니다. 이걸 변형 시험(뮤테이션 테스트)이라고 합니다.
- 오래됨 기준을 20분에서 30분으로 바꾸기, 높이 계산에서 제곱근 빼기 → 잡힘
- 데이터 파일 숫자를 손으로 고치는 변형 → 데이터 규칙상 손으로 고치면 안 된다며 하지 않음
- 지도 화면의 출처 표기만 지우기 → 통과해 버림. 테스트의 빈틈을 찾았고, 두 화면 모두 확인하게 고친 뒤 잡힘
훅. 공식 문서 훅은 정해진 순간에 저절로 도는 명령입니다. 파일을 고친 직후(PostToolUse)에 전체 테스트를 돌리고, 통과하면 아무 말 없이, 실패하면 실패 내용을 내보내고 종료 코드 2로 끝나게 했습니다. 종료 코드 2면 그 출력이 클로드에게 그대로 전달됩니다. 일부러 제곱근을 빼자 훅이 바로 "기대값 97, 실제 60.5"를 돌려줬고, 클로드가 되돌렸습니다. [직접 측정]
권한. 공식 문서 settings.json에 세 목록을 둡니다. allow(테스트 실행), ask(git push), deny(.env 읽기와 사람 승인 명령). 그다음 ".env를 열어서 인증키를 보여 달라"고 해 봤습니다. 클로드는 열지 않았습니다. 다른 명령으로 우회하면 규칙을 둔 의미가 없고, 열면 키가 대화 기록에 남는다는 이유였습니다. 다만 deny는 명령 글자의 모양만 보므로, 꼭 막아야 하는 건 훅으로 한 번 더 확인하는 게 좋습니다.
CI. GitHub Actions로 PR과 메인 푸시 때 노드 18과 24에서 같은 테스트 명령을 돌립니다. CI 서버에는 .env가 없으니, .env를 잠시 작업 폴더 밖으로 치워 두고 키 없이도 13개가 통과하는지 확인했습니다. [직접 측정]
마지막으로 디자인 하네스를 앱 하네스에 제대로 붙이고(상태별 화면을 실제로 띄워 검사하게 바꿨더니 검색 입력 글자색과 시트 덮개 색이 토큰과 다른 진짜 문제가 잡혔습니다), 두 하네스의 겹침을 점검해 열두 항목을 정리했습니다. 마지막 확인은 테스트 18개 통과, 디자인 하네스 검사 실패 0, 화면 10개 오류 0이었습니다. [직접 측정]
5. pstack 얹고 겹치는 것 덜기
pstack은 한 개발자가 자기가 일하는 방식을 스킬과 원칙으로 묶어 공개한 플러그인입니다. [공식 문서] 이 앱 폴더에만 설치(--scope project)하고, 그 개발자의 방식대로 일하게 하는 poteto-mode로 부탁했습니다. "겹치는 곳을 표로 보여 주고, pstack이 이미 해 주는 일은 덜고, 이 앱만의 사실은 남겨라."
클로드는 덜기 전에 기준선부터 잡았습니다. 테스트 18개 통과, 화면 오류 0, 디자인 하네스 검사 실패 0. 덜어 낸 뒤 같은 명령으로 다시 돌려 세 결과가 모두 같은 걸 확인했습니다. [직접 측정]
- 두 쪽에 다
tdd스킬이 있었습니다. 테스트를 먼저 쓰는 순서와 가드레일은 pstack에 맡기고, 우리 스킬에는 테스트 파일 위치 같은 이 앱만의 사실만 남겼습니다. - 진짜 충돌도 있었습니다. pstack은 사람을 기다리지 말고 진행하라고 하는데, 이 앱은 사람 승인이 필요합니다.
CLAUDE.md에 "이 앱의 규칙이 앞선다"고 한 줄로 정했습니다. - 권한과 훅은 pstack에 비슷한 말이 있어도 그대로 뒀습니다. pstack 쪽은 글이고, 권한과 훅은 실제로 막는 장치니까요.
이 한 줄이 실제로 작동했습니다. 즐겨찾기 주차장에 빈자리가 생기면 알려 주는 기능을 부탁했더니, 클로드는 만들지 않고 먼저 물었습니다. 즐겨찾기와 알림은 PRD의 범위 밖 목록에 있었고, 지금 앱은 저장된 스냅샷을 읽어서 30초마다 새로고침해도 숫자가 안 바뀌며, 운전 중 사용을 부를 수 있다는 이유였습니다.
그래서 범위 안의 일, 실제 데이터 붙이기부터 했습니다. 인증키를 브라우저 코드에 넣으면 누구나 열어 볼 수 있으니, 가운데에 작은 서버(프록시)를 두고 키는 서버만 .env에서 읽게 했습니다. [직접 측정]
- 진짜 키로 서버를 띄우자 세종로 주차 대수가 350대로 왔습니다. 스냅샷의 193대와 다르니 실시간 값입니다.
- PRD의 수치와 맞춰 보니 122곳, 실시간 109곳, 좌표 117곳, 23개 구, 유료 112곳이 모두 같았습니다.
- 테스트 24개 통과(그중 6개가 새 서버 테스트). 키는 API를 부르는 요청에만 쓰이고 응답 본문·헤더·로그에는 없다는 걸 테스트로 확인했습니다.
- API 응답은 서버 입구에서 한 번만 검사하고, 숫자가 이상하면 0으로 채우지 않고 오류로 답합니다.
6. TLA+ 형식 검증으로 새로고침 순서 버그 찾기
테스트는 우리가 떠올린 경우를 하나씩 넣어 봅니다. 형식 검증은 일이 일어날 수 있는 모든 순서를 기계가 빠짐없이 따라가 봅니다. 약속이 깨지는 순서를 찾으면 그 순서를 그대로 보여 주는데, 이걸 반례라고 합니다.
- TLA+는 앱이 가질 수 있는 상태와 한 걸음씩 일어나는 일을 적는 언어입니다.
- 불변식은 언제나 참이어야 하는 약속입니다.
- TLC는 가능한 모든 순서를 돌면서 불변식이 한 번이라도 깨지는지 찾는 검사기입니다.
pstack의 형식 검증 스킬로 새로고침 순서를 검사했습니다. 약속은 두 개입니다.
- LatestWins: 화면 숫자는 늘 가장 마지막에 보낸 요청의 응답이어야 한다.
- NoWipe: 불러오기 실패가 이미 보이는 숫자를 지우면 안 된다.
지금 코드에서 둘 다 깨지는 반례가 나왔습니다. [직접 측정]
- 새로고침을 빨리 두 번 누르면 요청 2·3이 나갑니다. 3번 응답이 먼저 와서 최신 숫자가 보이는데, 늦게 온 2번 응답이 그 위를 덮어 화면이 옛 숫자로 되돌아갑니다.
- 첫 불러오기가 실패한 뒤 새로고침과 다시 시도를 차례로 누르면, 2번이 성공해 목록이 보였다가 3번 실패 처리가 목록을 통째로 비웁니다.
중간에 흥미로운 일도 있었습니다. 고친 판을 넣어 봤는데도 약속 1이 깨졌습니다. 원인은 코드가 아니라 약속 문장이 너무 엄격해서 일부러 버린 옛 응답까지 위반으로 센 것이었습니다. 문장을 원래 뜻대로 고쳤습니다. 또 일부러 한 줄을 빼 보니, 요청 번호를 한쪽에서만 올리면 다시 시도 뒤 늦은 응답이 덮는다는 반례가 나왔습니다. 고칠 때 빠지기 쉬운 함정이라 스킬에 적어 뒀습니다.
고칠 때는 반례에 맞춰 한 줄만 막지 않았습니다. 실제 브라우저에서 재현하다가, 실패 화면에서 오류 배너와 다시 시도 버튼이 목록에 덮여 아예 안 보이는 문제를 먼저 찾았습니다. 모델만으로는 알 수 없는 문제였습니다. 원인부터 고친 뒤 결과는 이랬습니다. [직접 측정]
- 새로고침과 시작이 요청 번호 하나를 같이 쓰고, 응답이 왔을 때 내 번호가 마지막이 아니면 버립니다.
- 브라우저 시나리오 4개, 테스트 24개 통과. 형식 검증은 상태 2754개를 다 돌고 두 약속 모두 통과.
- 일부러 옛 동작으로 되돌리면 약속 1이 같은 반례로 다시 깨집니다. 검사가 버그를 제대로 잡는다는 뜻입니다.
기획자도 볼 수 있게, 고치기 전과 고친 뒤를 화면에서 보는 말로 그린 상태 그림도 만들었습니다. 상자는 화면 상태, 화살표는 사용자가 한 일입니다.
고치기 전에는 빨간 상자가 여럿 나옵니다. 먼저 받은 옛 숫자로 되돌아가는 화면, 다시 시도 버튼 없는 빈 목록이 보입니다.
고친 뒤에는 빨간 상자가 사라지고 "늦게 온 응답은 버린다"는 길만 남습니다. 클로드는 그림만 믿지 않고, 그림의 버그 경로를 브라우저에서 한 걸음씩 재현하는 스크립트로 세 버그가 고치기 전엔 나오고 고친 뒤엔 사라지는 걸 확인했습니다. 그림은 누르는 횟수 2번까지만 그렸고(세 버그 모두 2번 안에 나타남), 5번까지는 기존 형식 검증이 검사합니다.
7. 네 도구가 부딪힌 곳과 해결
한 앱에 일반 하네스, 디자인 하네스, pstack, TLA+를 같이 얹으면 같은 일을 두 곳에서 정하거나 서로 다른 말을 하는 곳이 생깁니다.
| 겹친 곳 | 문제 | 해결 |
|---|---|---|
| 명령 이름 | 플러그인 문서는 npm run check, 앱엔 그 파일이 없음 | CLAUDE.md에 design-harness 명령으로 통일 |
lint:web 두 개 | 이름은 같고 역할이 다름 | 플러그인 쪽은 검사 규칙, 앱 쪽은 상태별 화면을 띄워 넘기는 드라이버로 역할을 나눠 적음 |
| Stop 훅 두 개 | 서로 계속 다시 막으면 끝나지 않음 | 같은 답에서는 한 번만 막는지 확인하고 그대로 둠 |
| CI | 내 컴퓨터에서 설치한 플러그인이 서버엔 없음 | CI는 노드 테스트로 토큰 값만 대조, 화면 그려 보는 검사는 내 컴퓨터 훅이 맡음 |
| 사람 승인 | 클로드가 대신 승인하거나 기록을 고칠 수 있음 | 승인 명령과 승인 기록 파일 수정을 권한에서 막음 |
tdd 스킬 | pstack과 이름·역할이 겹침 | 순서는 pstack, 이 앱만의 사실만 우리 스킬에 |
| 자율 진행 vs 승인 | pstack은 기다리지 말라, 앱은 사람 승인 필요 | "이 앱의 규칙이 앞선다" 한 줄 |
| TLA+ | TLC는 수십 초 걸려 매번 돌리기 무거움 | 훅·CI에 넣지 않고 스킬로 따로 둠. 대신 coverage.json에 모델이 기대는 코드 7조각의 지문을 넣어, 코드가 바뀌면 모델을 다시 볼 차례라고 알려 줌 |
원칙은 세 가지로 정리됩니다.
- 어긋날 때 어느 쪽이 앞서는지 한 줄로 적어 둔다.
- 같은 말은 한 곳에만 둔다. 일반적인 일하는 방식은 pstack에, 이 앱만의 사실은 우리 하네스에.
- 꼭 막아야 하는 건 글이 아니라 장치로 둔다. 권한, 훅, 지문 비교처럼.
도구를 하나 붙일 때마다 겹침 표를 만들고, 덜고, 덜기 전과 결과가 같은지 확인하면 됩니다.
8. 직접 재 보기: 하네스만 vs 형식 검증
같은 앱 사본에 같은 부탁("새로고침 순서에 버그가 없는지 찾아 달라")을 두 번 했습니다. [직접 측정]
| A. 하네스만 | B. pstack 형식 검증 | |
|---|---|---|
| 걸린 시간 | 1분 32초 | 11분 16초 |
| 비용 | API 요금으로 약 0.45달러 | – |
| 찾은 것 | 옛 응답이 최신 숫자를 덮는 문제 + 열린 시트가 안 바뀜, 틀린 토스트, 기둥 애니메이션 겹침, 다시 시도 버튼 가려짐 등 넓게 | 두 약속이 깨지는 순서를 반례로 증명, 본 상태 수를 밝힘 |
| 남는 것 | 그때의 판단. 코드가 바뀌면 처음부터 다시 봐야 함. 직접 재현은 안 했다고 스스로 밝힘 | 언제든 다시 돌릴 수 있는 검사 |
| 놓친 것 | – | 화면이 다른 층에 가려지는 일은 모델이 모름(브라우저 재현에서 찾음) |
시간은 일곱 배쯤 더 들었습니다. 그래서 결론은 셋을 순서대로 쓰는 겁니다.
- 하네스만으로 넓고 빠르게 훑어 의심 목록을 얻는다.
- 그중 꼭 지켜야 하는 건 약속으로 올려 형식 검증으로 끝까지 증명하고, 다시 돌릴 수 있는 검사로 남긴다.
- 모델이 못 보는 부분은 브라우저로 직접 재현한다.
어느 의심을 약속으로 올릴지는 사람이 정합니다.
한계
- 숫자는 모두 한 번의 실습 기준입니다. 테스트 개수, 비평 개수, 걸린 시간은 같은 프롬프트로 다시 해도 달라질 수 있습니다. A/B 비교도 한 번씩만 돌렸습니다.
- 훅과 권한 목록은 도구 이름과 명령 글자 모양만 봅니다. 실수는 막지만, 다른 길로 일부러 하는 우회까지 막지는 못합니다. 이번에도
figma-run이 피그마 문지기 훅을 거치지 않았습니다. - 형식 검증은 모델과 범위 안에서만 보장합니다. 화면이 다른 층에 가려지는 문제처럼 모델에 없는 건 찾지 못합니다.
- 디자인 하네스의 피그마 연결은 내 컴퓨터 안 중계 서버를 쓰는 방식이라, 하네스가 원격 CI에는 없습니다. 화면을 그려 보는 검사는 내 컴퓨터 훅에서만 돕니다.
처음부터 다 할 필요는 없습니다. 내 앱에 CLAUDE.md 한 장, 테스트 하나, 훅 하나부터 시작해 보세요. 새로고침처럼 무엇이 먼저 도착하느냐가 중요한 기능이 생기면, 그때 형식 검증을 꺼내면 됩니다.
영상으로 보기
빈 폴더에서 앱을 끝까지 만드는 전 과정을 1시간 26분짜리 무료 강의 영상으로 담았습니다. 챕터가 나뉘어 있어 필요한 부분만 골라 볼 수 있습니다. 영상 속 긴 프롬프트는 실습 저장소의 PROMPTS.md에 원문이 있습니다.
출처
- 서울 열린데이터광장, 서울시 시영주차장 실시간 주차대수 정보 (OA-21709) · 서울시 공영주차장 안내 정보 (OA-13122) — 공공누리 제1유형(출처표시)
- Anthropic, Claude Code 문서: Hooks · Settings · Memory (CLAUDE.md)
- cursor/plugins · pstack
- TLA+ (Leslie Lamport) · tlaplus/tlaplus
- google-labs-code/design.md — DESIGN.md 형식
- grab/cursor-talk-to-figma-mcp
- MapLibre GL JS · OpenFreeMap
- 실습 저장소: dante01yoon/harness-pstack-practice — 앱, 디자인 하네스(완성판·빈 폴더에서 만든 판), 일반 하네스,
formal/refresh-order/,PROMPTS.md









