같은 설명을 두 번 했다면 스킬부터

2026년 6월 12일 | 바이브코딩 Tips

---

코딩 에이전트에게 같은 설명을 두 번 반복했다면, 나는 요즘 채팅창을 더 길게 쓰기보다 스킬부터 확인한다. 한 번은 실수라고 볼 수 있다. 그런데 같은 금지 경로를 또 건드리거나, 같은 검증 명령을 또 빠뜨리거나, 완료 보고에서 같은 미확인 항목을 또 뭉개면 그건 프롬프트가 짧아서가 아니라 반복 규칙이 저장되는 위치가 잘못된 신호에 가깝다.

예전에는 이런 일이 생기면 대화 첫머리에 주의사항을 더 붙였다. “이 파일은 건드리지 말 것”, “테스트 결과와 미확인 범위를 나눠 쓸 것”, “수정 전에 설정 파일을 먼저 읽을 것” 같은 문장을 계속 늘렸다. 당장 한 세션에서는 효과가 있다. 문제는 다음 세션, 다른 모델, context compaction 뒤에 같은 문장이 다시 사라진다는 점이다. 사람은 기억한다고 착각하지만, 에이전트 입장에서는 그 규칙이 매번 새로 흘러 들어오는 말풍선일 뿐이다.

스킬은 완성된 매뉴얼보다 수리 기록에 가깝다

스킬을 처음부터 완벽한 운영 문서로 만들려고 하면 금방 무거워진다. 나는 오히려 실패가 난 뒤에 한 줄씩 고치는 쪽이 오래 간다고 느꼈다. 에이전트가 테스트를 빠뜨렸다면 “완료 전 검증 명령을 실행한다”를 길게 쓰기보다, 어떤 상황에서 어떤 검증을 첫 번째 증거로 삼을지를 좁혀 둔다. 에이전트가 관련 없는 파일까지 손댔다면 “주의해서 수정하라”가 아니라, 수정 허용 경로와 확장 요청 조건을 스킬에 넣는다.

이 차이가 작아 보여도 실제 작업에서는 꽤 크다. 주의사항은 대체로 감정적인 문장으로 남는다. “조심”, “꼼꼼히”, “실수하지 말기” 같은 말은 사람이 읽기에는 편하지만, 다음 행동을 잘라 주지는 못한다. 반면 스킬에 남기는 수리 기록은 가능하면 행동 단위여야 한다. 무엇을 먼저 읽을지, 어디까지 바꿀 수 있는지, 어떤 출력이 있어야 끝났다고 볼지, 몇 번 실패하면 멈출지 같은 식이다.

내가 남기는 네 줄

요즘은 같은 실수가 반복되면 스킬 파일을 크게 갈아엎기보다 아래 네 줄만 먼저 본다. 전부 채울 필요는 없지만, 적어도 한 줄은 실패 원인과 직접 연결되어 있어야 한다.

• 호출 조건: 이 스킬을 언제 불러야 하는가. 반대로 언제 불러오면 안 되는가.
• 첫 행동: 수정 전에 반드시 읽을 파일, 로그, 설정, 공개 문서가 무엇인가.
• 검증 증거: 완료 보고에 어떤 명령 결과나 화면 확인이 들어가야 하는가.
• 중단 조건: 실패가 몇 번 반복되면 더 진행하지 않고 멈춰야 하는가.

예를 들어 어떤 에이전트가 설정 파일을 보지 않고 바로 코드를 고쳐서 문제가 생겼다면, 나는 스킬에 이런 식의 짧은 문장을 추가한다.

이 작업에서는 수정 전에 설정 파일과 실패 로그를 먼저 읽는다.
수정 경로가 처음 허용한 범위를 벗어나면 바로 멈추고 확장 이유를 보고한다.
완료 보고에는 실행한 검증과 아직 확인하지 않은 항목을 분리한다.

별것 아닌 문장처럼 보이지만, 이 정도만 있어도 다음 세션의 첫 움직임이 달라진다. “해결해 줘”라는 넓은 요청이 들어와도 에이전트가 곧장 edit으로 뛰지 않고, 최소한 읽기와 검증 표면을 먼저 잡는다. 스킬이 좋은 이유는 모델에게 더 많은 지식을 먹여서가 아니라, 매번 잊히던 작업 습관을 작업 시작점에 다시 걸어 두기 때문이다.

대화에 남길 것과 스킬에 남길 것

모든 메모를 스킬로 보낼 필요는 없다. 한 번만 필요한 판단, 특정 브랜치의 임시 상태, 오늘만 쓰는 파일명은 대화나 작업 노트에 남기면 충분하다. 스킬로 올릴 만한 것은 반복 가능성이 있는 실패다. 같은 종류의 작업을 다시 맡길 때도 유효하고, 다른 저장소에서도 비슷하게 적용될 수 있고, 문장 하나로 다음 행동이 달라지는 내용이면 스킬 후보로 본다.

반대로 스킬이 너무 자세해지면 또 다른 문제가 생긴다. 에이전트가 본문을 읽느라 현재 작업의 증거를 덜 보거나, 오래된 예외 규칙을 지금 상황에 억지로 맞출 수 있다. 그래서 나는 실패 하나에 스킬 수정 하나를 붙이는 편을 선호한다. 긴 회고를 통째로 옮기지 않고, “다음에 같은 실수가 나지 않게 만드는 최소 문장”만 남긴다.

실패를 문장으로 바꾸는 순서

스킬을 고칠 때 가장 조심하는 부분은 실패 원인을 너무 크게 해석하지 않는 것이다. 에이전트가 테스트를 안 돌렸다고 해서 “검증을 더 철저히 하라”를 넣으면 다음에도 비슷하게 흐려진다. 대신 나는 실패 로그를 보면서 질문을 하나만 던진다. “다음 세션이 이 장면을 다시 만났을 때, 첫 5분 안에 다르게 할 행동은 무엇인가.” 이 질문에 답하지 못하는 문장은 스킬에 넣지 않는다.

실패 패턴도 조금 나눠서 본다. 첫째, 읽기 부족이면 첫 행동을 고친다. 관련 문서, 설정 파일, 기존 테스트, 최근 변경 로그 중 무엇을 먼저 볼지 지정한다. 둘째, 수정 반경 확대이면 허용 경로와 멈춤 조건을 고친다. 셋째, 완료 보고의 흐림이면 검증 증거와 미확인 항목을 분리하게 만든다. 같은 “실패”라도 어느 줄을 고쳐야 하는지가 다르다.

이렇게 나누면 스킬이 잡다한 잔소리 모음이 되는 일을 조금 막을 수 있다. 실패가 읽기 문제였는데 중단 조건만 길어지면 다음 세션은 여전히 잘못된 파일을 본다. 완료 보고가 문제였는데 호출 조건만 바꾸면 마지막 확인이 다시 흐려진다. 스킬 패치는 문장 수보다 위치가 중요하다. 어디에 한 줄을 넣느냐가 다음 행동의 방향을 바꾼다.

스킬도 낡는다

스킬을 만들어 두면 끝이라고 생각하기 쉽지만, 실제로는 스킬도 코드처럼 낡는다. 도구 이름이 바뀌고, 검증 명령이 바뀌고, 프로젝트 구조가 바뀐다. 예전에는 맞았던 중단 조건이 지금은 너무 보수적일 수도 있다. 그래서 같은 설명을 반복하게 되는 순간은 귀찮은 일이 아니라 꽤 좋은 신호다. 스킬이 현재 작업 방식과 어긋났다는 알림이기 때문이다.

내 기준은 단순하다. 에이전트에게 같은 말을 두 번 했다면, 세 번째에는 말풍선에 더 붙이지 않는다. 그 문장을 스킬의 호출 조건, 첫 행동, 검증 증거, 중단 조건 중 어디에 넣을지 본다. 그렇게 한 줄씩 고친 스킬은 거창한 자동화보다 덜 멋있어 보이지만, 실제 세션에서는 훨씬 덜 흔들린다.

그리고 고친 뒤에는 다음 작업에서 일부러 한 번 확인한다. 스킬이 정말 먼저 불렸는지, 첫 행동이 읽기였는지, 완료 보고가 검증과 미확인을 나눴는지 보는 정도다. 이 확인을 하지 않으면 스킬은 금방 “좋은 말이 적힌 문서”가 된다. 작은 문장 하나를 고쳤다면, 그 문장이 다음 실행에서 실제 행동으로 바뀌었는지까지 봐야 한다. 그래야 스킬이 기억 저장소가 아니라 작업 습관을 갱신하는 장치가 된다. 나는 이 확인을 통과한 문장만 남기고, 실행에 별 영향을 주지 못한 문장은 다음 정리 때 과감히 지운다. 스킬은 길수록 좋은 문서가 아니라, 다음 실행을 한 칸 덜 흔들리게 만드는 작은 장치에 가까워야 한다. 그래야 다음 실패도 고칠 수 있는 크기로 작게 남고, 다음 손실도 줄어든다.