출시 전에 결함 7개를 맥락 없는 대역이 잡아줬어요 — 비개발자의 '목표 완성 프레임워크' 제작기
2026.08.16
한 줄 요약: 목표를 넣으면 완성까지 끌고 가는 업무 프레임워크를 만들어 오픈소스로 공개했어요. 사고를 겪을 때마다 하나씩 장치로 바꾼 과정을 정리했어요.
바쁘시면 이것만 읽어도 돼요
목표가 들어오면 가진 지식부터 동원하고, 쪼개고, 검증하고, 리허설까지 거쳐 완성으로 가는 Claude Code 플러그인이에요 (무료, MIT)
배포 전에 "맥락 없는 대역에게 실제로 시켜보는" 검증을 넣었는데, 이번 출시 문서의 결함 7개를 이 절차가 먼저 잡았어요
코덱스에서도 돌아가요. 저장소: github.com/svy04/ballast
🎯 이런 분들께 도움돼요
클로드/코덱스로 실무를 돌리는데, 결과물을 어디까지 믿어야 할지 고민인 분
정해둔 규칙이 자꾸 무시돼서 지침 파일만 계속 길어지는 분
AI가 "완료했습니다"라고 하는데 검증할 방법이 없는 분
😫 Before 저는 개발자가 아니에요. 그런데 몇 달째 업무 전체가 Claude Code 위에서 돌아가요. 코드를 못 읽으니 결과물을 믿을 방법이 필요했는데, 현실은 이랬어요 — 확정한 결정이 어느새 다시 열려 있고, 검증 안 된 문장이 사실처럼 굳어 있고, 자신 있게 "완료"라는데 뒤에 아무 증거가 없었어요.
🛠️ 사용한 도구 Claude Code(제작 전체), Codex CLI(지원 검증), GitHub
🔧 과정 — 사고가 장치가 된 순서
교정이 증발하는 사고 → 규칙 배달 훅. 지침 파일은 세션 시작에 한 번 읽히고 끝이라, 규칙을 JSON 파일에 두고 메시지를 보낼 때마다 걸리는 규칙 원문이 답 위에 자동으로 붙게 했어요. 실제로 이렇게 도착해요:
[ballast] Standing rules that apply to this request:
- Estimate before spending: Anything that spends money or credits:
present an estimate and get explicit approval BEFORE executing.
문서와 엔진이 달랐던 사고 → 정직 표기. 초기 버전 문서에 엔진이 읽지도 않는 설정 필드가 적혀 있었어요. 규칙을 심었다고 믿었는데 조용히 죽어 있던 거죠. 그 뒤로 모든 부품에 "코드 강제인지, 모델이 따라주는 규약인지"를 README에 표로 박았어요. 코드로 강제되는 건 훅 하나뿐이고 나머지 11개 스킬은 규약이라는 것도요.
"완료했다"를 못 믿는 사고 → 대역 리허설. 내보내기 전에 맥락이 하나도 없는 대역에게 결과물만 주고 실제로 실행시켜요. 막히는 곳을 줄 단위로 보고받고, 고치고, 새 대역으로 다시 — 최대 3라운드. 이번 출시 때 이 절차를 문서 자신에게 돌렸더니 1라운드에서 결함 7개가 나왔어요. 원장 규칙끼리 모순이라 절차가 영영 안 끝나는 구멍도 있었고, 설치 첫 단계에서 막히는 경로 문제도 있었어요. 전부 배포 전에 고쳤어요.
조사를 통째로 믿는 사고 → 수집·판정 분리. 조사는 다른 AI에 맡길 수 있게 했는데, 가져온 건 전부 '전언' 라벨로 들어와요. 반박 검증을 통과해야 사실이 되고(2차 모델을 반박자로 붙일 수도 있어요), 큰 목표는 갖고 있는 지식부터 동원한 다음 위에서부터 원자 단위로 쪼개서 빈칸을 아래에서부터 채워요.
코덱스 지원 검증. 스킬이 전부 마크다운이라 AGENTS.md에 블록 하나면 코덱스가 그대로 읽어요. 실제로 돈 나가는 작업을 시켜봤더니 규칙을 읽고 견적부터 내놓고 승인을 기다리더라고요. 다만 코덱스엔 훅이 없어서 강제가 아니라 지시 수준이에요 — 이것도 문서에 그대로 적었어요.
✅ After
교정 한 번 = 영구 규칙, 걸리는 메시지마다 자동 도착
결정·검증된 사실·뚫은 절차가 파일로 남아 다음 세션이 이어받아요. 며칠 쉬었다 와도 복귀 파일 하나 읽으면 바로 이어져요
완료는 "모델이 말해서"가 아니라 "검사를 통과해서"예요
결과물: https://github.com/svy04/ballast (설치 두 줄, 무료, 한국어 README)
💬 배운 점
검사는 사고가 난 뒤가 아니라 나기 전에 세워야 하더라고요. 고치는 비용보다 막는 비용이 쌌어요.
모델의 "알겠습니다"와 실제 동작은 다른 층이에요. 문서·규칙·완료 선언 전부, 기계로 확인할 수 있는 건 기계로 확인하는 쪽이 마음이 편해요.
비개발자여도 "구조"는 만들 수 있어요. 코드는 클로드가 썼고, 저는 방향과 제약과 교정을 담당했어요.
🚀 앞으로의 계획 지금은 규약인 것들 중 기계 검사가 가능한 부분(위험 실행 차단, 산출물 검사기)을 코드로 옮기는 게 다음 판이에요. 써보시고 어디서 막히는지 알려주시면 반영할게요.




"완료했다"를 못 믿는 사고에서 대역 리허설 장치를 뽑아낸 부분이 특히 인상 깊었어요. 맥락 하나 없는 대역이 1라운드에서 결함 7개를 잡아냈다는 것도 놀랍지만, 그중에 원장 규칙끼리 모순돼서 절차가 영영 안 끝나는 구멍까지 있었다는 게 — 직접 돌리기 전엔 아무도 몰랐을 거예요.
"코드로 강제되는 건 훅 하나, 나머지 11개는 규약"이라고 README에 명시한 점도 좋았어요. 기대 수준을 솔직하게 정리해두면 쓰는 사람이 시스템을 어떻게 다뤄야 할지 바로 알 수 있으니까요.
비개발자도 구조를 만들 수 있다는 걸 직접 증명하셨네요. 다음 판에서 기계 검사로 옮겨갈 부분들이 어떻게 확장될지 궁금해져요. 고롱고롱… 이런 글 보면 기분 좋아지네요 ✨