실패 20건에서 뽑아낸 코딩 규칙집

실제 실패 사례 하나에서 규칙 하나를 뽑아 만든 클로드 코드(Claude Code) 스킬 모음집 웻스톤(Whetstone)이 공개됐다. 스킬 20개, 실패 20건. 제작자는 모든 스킬은 흉터라는 원칙을 내세워, 가설이나 일반론으로 쓴 조언은 아예 넣지 않았다고 밝혔다.

무슨 일인가 / 배경

스킬은 에이전트가 특정 상황에서 불러 쓰는 짧은 규칙 묶음이다. 웻스톤의 구조는 단순하다. 폴더 하나에 SKILL.md 하나, 내용은 순수 마크다운이다. 앞머리에 이름과 설명을 두고 이 설명이 언제 이 규칙을 꺼낼지 판단하는 방아쇠 역할을 한다. 클로드 코드 전용 요소는 플러그인 자동 인식뿐이라, 파일 자체는 다른 에이전트에도 그대로 붙일 수 있다.

설치는 클로드 코드에서 /plugin marketplace add iamakbarsha1/whetstone 한 줄이다. 라이선스는 CC BY 4.0으로, 출처를 밝히면 사내 문서로 가져다 쓸 수 있다. 수록 기준은 문체로 갈린다. 블로그 글처럼 읽히면 버리고, 새벽에 장애를 수습하는 사람이 반길 체크리스트처럼 읽히면 남긴다는 것이 제작자의 설명이다.

핵심 짚어보기

20개는 다섯 갈래로 묶여 있다. 검증·증명 6개, 계획·설계 6개, 안전한 변경 4개, 진단·리뷰 3개, 그리고 규칙을 만드는 방법 자체를 다룬 1개다. 대표적인 것을 우리 시각으로 풀면 이렇다.

실제 경로로 검증하라는 규칙은, 대역이 아니라 진짜 트리거와 진짜 데이터로 돌려보기 전에는 됐다고 말하지 말라는 것이다. 테스트가 실패할 수 있음을 증명하라는 규칙은 초록불을 믿기 전에 일부러 한 번 깨뜨려 보라고 요구한다. 폭발 반경을 훑으라는 규칙은 플래그·컬럼·타입·엔드포인트처럼 공유되는 약속을 바꿀 때, 사라진 옛 이름이 곧 사용처 색인이라는 점을 짚는다. 없다는 주장을 검증하라는 규칙은 위임한 조사에서 돌아온 없음이라는 답은 검색어 품질만큼만 믿을 수 있다고 경고한다.

마지막 하나는 흉터를 규칙으로 증류하는 절차 자체다. 실패에서 옮겨 쓸 수 있는 불변식 하나를 뽑아 정해진 양식에 넣고 검증기로 잠근다. 각 스킬은 사전 점검 목록으로 끝나며, 항목이 비어 있으면 조용히 넘어가는 대신 크게 실패하도록 설계됐다.

1인기업 실전 적용 포인트

• 20개를 통째로 넣지 않는다. 최근 석 달간 반복된 사고 유형에 맞는 2~3개만 골라 붙인다. 스킬은 매 세션 컨텍스트를 먹는 비용 항목이다.
• 이번 주 사고 하나를 골라 자기 버전을 만든다. 방아쇠 문구 한 줄, 원인 기전 세 줄, 사전 점검 세 줄이면 SKILL.md 한 장이 나온다. 이 절차 자체가 모음집 안에 규칙으로 들어 있다.
• 마크다운이라는 점을 활용한다. 같은 파일을 다른 에이전트의 시스템 프롬프트에 붙이거나, 사람이 쓰는 PR 체크리스트로 전용할 수 있다.
• 자동 승인 환경을 쓴다면 우선순위를 검증 계열에 둔다. 사람이 매번 확인하지 않는 구조에서는 실패하면 크게 실패하는 게이트가 사실상 유일한 제동 장치다.

전망 / 주의점

개인이 운영하는 프로젝트라 지속적인 관리가 보장되지는 않는다. 스킬이 늘어날수록 방아쇠 문구가 서로 겹쳐 엉뚱한 규칙이 불려 나오는 문제도 생긴다. 결국 남의 흉터는 출발점일 뿐이고, 내 저장소에서 한 번 돌려 확인하는 과정을 건너뛸 수는 없다. 그럼에도 실패를 재사용 가능한 형식으로 남기는 습관 자체는 도구가 바뀌어도 남는 자산이다.

출처: 웻스톤 프로젝트 (https://whetstone.akbarsha.dev/)