안녕하세요.

이 글은 CLAUDE.md, 스킬 및 에이전트 구조화하기에 대한 후속 글입니다. 해당 게시물 댓글에서 제가 완전히 건너뛰었던 실패 지점을 지적해 주셨고, 이 부분은 별도의 글로 작성할 가치가 있습니다: 스킬 본문(skill body)은 완벽해도 에이전트가 여전히 이를 읽지 못하는 경우가 있습니다.

눈에 보이지 않는 병목 현상

스킬은 지연 로딩(lazily load)됩니다. 그것이 핵심입니다. 트리거되기 전까지 모델이 볼 수 있는 유일한 것은 프론트매터(frontmatter)의 한 줄짜리 description뿐입니다. 이는 라우팅 정확도가 인접한 스킬들을 단 하나의 문장으로 얼마나 잘 구별할 수 있는지에 의해 제한된다는 것을 의미합니다.

모든 본문을 감사하고, 모든 코드 예제를 코드베이스와 비교하며, 콘텐츠에 대한 검색 테스트를 실행할 수는 있지만... 모델이 잘못된 스킬을 선택하거나, 아무 스킬도 선택하지 않거나, 또는 문장이 이미 필요한 모든 정보를 전달했다고 판단하면 그 어떤 것도 중요하지 않습니다.

확인해야 할 두 가지 실패 모드가 있습니다.

실패 1: 스킬을 대체하는 설명(description)

# BAD - description 자체가 절차임
description: 테스트를 실행하고, 약화된 어설션(assertions)을 확인하며, 통과/실패 여부를 보고하여 완료된 작업을 검증함

모델은 그 문장을 읽고 이미 절차를 알고 있다고 느끼며, 메모리에서 얕은 버전(shallow version)을 실행합니다: 테스트 실행, diff 살펴보기, 보고. 실제 핵심 내용이 담긴 본문(

둘 다 동일한 문구로 시작합니다. 모든 테스트 작업이 A와 일치하며, 더 깊은 단계인 B는 결코 로드되지 않습니다. 여기에 함정이 있습니다. 본문(body)을 다시 작성해도 아무것도 변하지 않습니다. 모델은 그 문장을 넘어가지 못하기 때문입니다. 스킬 B를 영원히 다듬는다 해도 그것은 계속 보이지 않는 상태로 남을 것입니다.

차별화된 트리거(trigger)를 사용하여 설명(description) 단계에서 이를 해결하세요:

# skill A
description: 컴포넌트나 순수 함수(pure functions)를 위한 단위 테스트(unit tests)를 작성하거나 수정할 때 사용하십시오. 엔드포인트(endpoint)나 데이터베이스(database) 테스트용이 아닙니다.
...

문서를 테스트하듯 설명을 테스트하라

이전 포스트에서 저는 문서 본문(doc bodies)을 대상으로 검색(retrieval) 테스트를 수행했습니다. 서브에이전트(subagent)에게 저장소(repo) 접근 권한 없이 문서만 제공하고, 구현 관련 질문에 답하게 한 뒤 코드베이스(codebase)를 기준으로 채점하는 방식이었습니다. 여기서 확장된 방법은 설명(descriptions)만을 대상으로 두 번째 버전을 실행하는 것입니다.

서브에이전트에게 스킬 설명 목록만 제공하고 다른 것은 아무것도 주지 않은 채, 실제 작업 프롬프트(task prompts)를 입력합니다:

"orders 엔드포인트를 위한 통합 테스트(integration test)를 작성해줘."
"리팩터링(refactor)이 완료되었으니 마무리해줘."
"이 불안정한(flaky) 단위 테스트를 수정해줘."

단 한 가지만 질문하십시오: 어떤 스킬을 로드할 것이며, 그 이유는 무엇인가? 라우팅(routing)을 채점하십시오. 잘못된 스킬이 선택되거나, 아무것도 트리거되지 않거나, 모델이 "아무것도 로드할 필요가 없습니다. 설명이 무엇을 해야 할지 알려줍니다"라고 말한다면, 당신의 설명은 테스트에 실패한 것입니다. 본문이 아니라 문장을 수정하십시오.

경험 법칙 (Rule of thumb)

설명은 "지금 이 스킬을 로드해야 하는가?"에 답해야 하며, 결코 "로드되면 무엇을 할 것인가?"에 답해서는 안 됩니다.

만약 설명 내용을 실행할 수 있다면, 그것은 본문에 포함되어야 할 내용을 담고 있는 것입니다. 각 스킬에 대한 빠른 체크리스트는 다음과 같습니다:

• "...할 때 사용하십시오 (Use when ...)"로 시작하는가 (기능이 아닌 트리거)
• 인접한 스킬과 유사할 경우, 무엇을 위한 것이 아닌지 명시했는가
• 절차적 동사(run, check, verify, generate)를 포함하지 않는가
• 폴더 내의 어떤 두 스킬도 동일한 작업 프롬프트와 일치하지 않는가

한 줄의 프론트매터(frontmatter)가 그 아래에 있는 모든 것의 라우팅을 수행합니다. 그것이 매우 중요하므로, 중요한 것처럼 테스트하십시오. 실제로 중요하기 때문입니다.

도움이 되었기를 바랍니다!
Hash