자주 쓰는 스킬과 습관

워크플로우는 작업 하나가 거치는 본선 길이에요. 이 페이지는 그 길 옆에서 제가 실제로 부르는 스킬이에요.

본선은 정해진 순서로 돌지만, 옆 스킬은 제가 필요할 때 불러요. 코드를 쓰기 전에 읽고 캐묻는 쪽과, 쓴 뒤에 다시 보고 배우는 쪽으로 나뉘어요.

코드 전에 쓰는 것

/explore — 읽기 전용 fork

탐색은 fork 로 돌려요. fork 가 파일을 수십 개 읽어도 메인 세션에는 결론만 돌아와요. 실행하는 서브에이전트(explorer)에는 Edit·Write 가 아예 없어요. 탐색하다가 "이참에 고쳐 둘게요"가 일어날 수 없어요.

규칙 하나를 같이 둬요. 탐색 리포트를 받은 뒤 제 지시 없이 바로 구현하지 않아요. 리포트가 틀렸을 때 그걸 읽고 판정하는 사람이 저여야 하기 때문이에요. 처음 보는 레포에서는 --onboard 로 구조부터 잡아요.

/investigate — 빨간 신호 없이는 가설을 세우지 않아요

결함 조사의 첫 단계는 게이트예요. 실패하는 테스트나 재현 명령처럼 빨간 신호가 없으면 가설로 넘어가지 않아요. 신호 없이 세운 가설은 그럴듯한 이야기로 끝나기 쉬워요.

이 스킬은 분석만 해요. 원인과 근거를 .claude/<날짜>/DEBUG-*.md 리포트로 남기고 끝내요. 고치는 건 부른 쪽("고쳐줘", /04-fix)이에요. 원인을 찾는 컨텍스트와 고치는 컨텍스트를 나눈 거예요. 이 리포트는 금요일 증류 레인이 지식 루프로 가져가요.

/grilling — 결정 나무를 끝까지 캐물어요

계획이나 결정을 놓고 에이전트가 저를 인터뷰해요. 한 라운드에 지금 열린 질문을 전부 번호를 붙여 내고, 질문마다 권장 답을 달아요. 동의하는 질문은 넘기고 갈리는 곳에만 길게 답하면 돼요. 가지가 전부 정해질 때까지 라운드를 이어 가요.

제가 만든 앱 hwip 의 컨셉 문서도 이 스킬 두 라운드로 정했어요. 핵심 사용자, 차별점, 답하는 방식(버튼·자유 입력·음성), 자동 응답 범위가 그때 표로 남았어요. 아이디어가 아직 말로만 있으면 /office-hours 를, 화면이나 상태 모델을 손으로 만져 봐야 정해지면 /prototype 을 먼저 써요.

코드 뒤에 쓰는 것

/review — 게이트 밖 diff 를 처음부터

/review 는 슬라이스 게이트(/03-review)를 거치지 않은 diff 에 쳐요. 제가 손으로 고친 것, 다른 세션이나 워커가 연 PR, 로컬 diff 가 대상이에요. 대화를 모르는 fresh 컨텍스트에서 돌아서, 제 세션이 "이건 괜찮아요"라고 믿는 부분도 처음부터 다시 봐요.

브랜치 전체 리뷰(--full)는 모델 둘로 교차해요(에이전트 설정). 한쪽에서만 나온 finding 은 표에 "only opus"·"only sonnet"으로 남아서, 모델 하나로 돌렸으면 놓쳤을 것이 몇 개였는지 보여요.

/simplify — 버그가 아니라 군더더기

리뷰가 버그를 찾는다면 /simplify 는 있는 헬퍼를 다시 만든 곳, 필요 없는 추상화, 빈 주석을 찾아 고쳐요. 큐를 다 비운 뒤 ship 전에 한 번 돌려요.

/explain-diff — 머지 전에 제가 배워요

diff 를 리뷰하는 대신 설명 페이지로 바꿔요. 배경, 직관, 파일별 워크스루, 그리고 에이전트가 확신 없이 내린 결정 목록과 퀴즈가 한 장의 HTML 로 나와요. 퀴즈는 에이전트가 쓴 변경을 제가 설명할 수 있는지 재는 장치예요. 설명하지 못하는 코드는 머지하지 않아요.

확신 없는 결정은 플랜 파일의 ## Outcome 에 - unsure: 줄로도 남아요. 금요일 증류가 그 줄을 지식베이스로 가져가요.

세션을 넘길 때

/summary 를 인자 없이 치면 지금 세션을 요약해요. 세션을 갈아탈 때는 두 모드를 써요. prompt 는 새 세션에 붙일 시작 프롬프트를 클립보드에 복사하고, handover 는 다른 디렉터리·하네스·사람에게 넘길 노트를 써요.

컨텍스트는 단계 경계에서만 비워요

/compact 와 /clear 는 어떤 스킬보다 자주 쳐요. 컨텍스트를 언제 비우느냐가 그만큼 자주 오는 결정이라서 규칙을 따로 뒀어요. 작업 단계(그릴링·구현·QA)의 경계에서만 정하고, 위에서부터 처음 맞는 것을 골라요.

1. 다음 단계가 이 단계의 원문을 1차 출처로 쓰거나 창이 넉넉하면 이어 가요.
2. 지금까지의 탐색과 결정이 다음 일과 무관하면 /clear 해요.
3. 작업이 다른 디렉터리·하네스·사람에게 넘어가면 /summary handover 로 노트를 써요.
4. AFK 로 돌릴 만큼 좁으면 서브에이전트에게 넘겨요.
5. 그 밖이면 /compact 해요.

자동 압축은 훅(compact-gate.py)이 단계 경계에서만 통과시켜요. 슬라이스 하나를 구현하다가 중간에 압축되면 실이 끊기기 때문이에요. 단계를 끝낸 응답은 끝에 <!-- phase-end --> 한 줄을 달아 경계를 알려요.

/model·/effort 는 메인 세션만 바꿔요. 서브에이전트 모델은 정의 파일에 고정돼 있어서(에이전트 설정) 메인을 내려도 리뷰 쪽은 그대로예요.

손에 익은 습관

원본 체크아웃에서는 브랜치를 못 따게 막았어요

커밋할 작업은 세션의 레포라도 git worktree 별도 체크아웃에서 해요. 처음에는 문장 규칙이었는데, 에이전트가 원본 체크아웃에서 checkout 으로 브랜치를 바꿔 버려서, 같은 레포에서 돌던 pi 가 master 위에서 구현하고 있던 일이 있었어요. 그 뒤로 훅(worktree-guard.py)이 원본 체크아웃의 checkout -b·switch -c 를 막아요. 같은 레포에 세션 여러 개를 띄우면 "브랜치를 바꾸지 마"라는 문장으로는 못 지켜요.

조사 리포트를 받아도 바로 구현시키지 않아요

탐색을 맡긴 서브에이전트의 리포트가 돌아오면, 에이전트는 그 리포트를 읽고 이어서 구현하고 싶어 해요. 실제로 두 번 그렇게 됐어요. 리포트가 틀렸거나 제가 원한 방향이 아니어도 코드는 이미 바뀌어 있었어요. 그래서 조사와 구현 사이에는 제 지시가 한 번 들어가야 해요. 이걸 막는 훅도 만들었다가 정상 흐름을 더 자주 막아서 지웠고, 지금은 규칙으로만 지켜요.

숫자는 그 턴에 센 것만 써요

에이전트는 기억에서 꺼낸 숫자도 잰 숫자와 같은 말투로 써요. 그래서 그 턴에 직접 센 수만 그대로 쓰게 하고, 기억에서 쓴 수에는 미측정을 붙이게 해요. 1차 출처를 확인하지 못한 사실에는 미검증을 따로 붙여요.

자리를 비우면 폰으로 답해요

세션은 hwip cc 로 띄워요. 평소에는 턴이 끝날 때 푸시 하나가 오는 게 전부예요. 폰에서 그 세션에 메시지를 보내면 세션이 원격 모드로 바뀌고, 그때부터 에이전트는 모든 응답을 버튼 2~4개가 달린 질문(hwip_ask)으로 끝내요. 저는 폰에서 버튼을 누르거나 한 줄 답하고, 끝내기 버튼을 누르면 다시 평소 모드로 돌아와요. 긴 작업이 제 답 하나 때문에 멈춰 있지 않게 하려는 거예요. 이 도구(hwip)는 제가 만들었어요.