mattpocock/skills

설치는 안 했습니다 — 이 레포 자신의 논리 때문입니다. 플러그인을 깔면 스킬 설명 25개가 매 턴 상시 컨텍스트에 얹히는데, 그게 정확히 이 레포가 하지 말라고 쓴 것입니다. 대신 그 교리 문서 한 장을 자로 삼아 제 스킬 96개를 재봤습니다. 결과가 이 페이지입니다 — 호출 축이 걸려 있는 건 1개였고, 나머지 95개의 설명 20,672자가 매 턴 상시 로드되고 있었습니다.

무엇을 파는 레포인가

슬래시 커맨드 묶음이다. 다만 셀링포인트가 “프로세스를 소유하는 프레임워크가 아니라는 것”이다. README가 경쟁자를 직접 지목한다.

그런 접근은 프로세스를 대신 소유해서 돕는다. 그러면서 통제권을 뺏고, 프로세스 자체의 버그를 고치기 어렵게 만든다. 이 스킬들은 작고, 고치기 쉽고, 조합 가능하게 설계됐다.

그리고 스킬을 나열하지 않는다. 에이전트가 자주 망하는 실패 모드 넷을 축으로 놓고, 각각에 처방 스킬을 붙인다.

실패 모드	진단	처방
원하는 걸 안 만든다	“아무도 자기가 뭘 원하는지 정확히 모른다” — 사람과 에이전트 사이의 소통 격차	압박 질문 세션
너무 장황하다	프로젝트 은어를 모르니 한 단어면 될 걸 스무 단어로 쓴다	공유 어휘 문서 + 도메인 모델링
코드가 안 돌아간다	피드백 루프 부재. 타입·브라우저·자동 테스트가 없으면 눈 감고 난다	TDD · 버그 진단
진흙 공을 만들었다	에이전트가 코딩을 가속하면 소프트웨어 엔트로피도 같이 가속된다	코드베이스 설계

두 번째 항목의 예시가 노골적이다. BEFORE: “코스 안 섹션 안의 레슨이 ’실체화’될 때(파일시스템에 자리를 받을 때) 생기는 문제” → AFTER: “실체화 연쇄에 문제가 있다.” 그리고 이걸 감성이 아니라 토큰 논리로 정당화한다 — 공유 언어가 있으면 에이전트가 사고에 쓰는 토큰이 준다.

스타는 207,586개인데 기여자는 3명이다. 생후 6개월에 20만은 저자의 뉴스레터 청중이 만든 숫자지 코드 검증량이 아니다. 다만 포크가 17,928개로 스타 대비 11.6 대 1이라, Odysseus의 450 대 1보다는 훨씬 건전하다 — 실제로 가져다 쓰는 비율이 있다는 뜻이다.

실제로 가져온 것 — 두 개의 부하

값어치는 스킬 35개가 아니라 그 스킬들을 어떻게 쓸지 규정한 교리 문서 한 장에 있다. 첫 문장이 목표를 정확히 규정한다.

같은 레버가 각각을 예측 가능하게 만든다 — 에이전트가 매 실행마다 같은 프로세스를 밟게 하는 것이지, 같은 출력을 내게 하는 게 아니다.

그 문서의 축이 비용이 두 종류라는 것이다.

부하	누가 지나	처방
컨텍스트 부하	기계 — 상시 로드되는 모든 줄. 발동하든 안 하든 매 턴 토큰과 주의력을 쓴다	최소화 대상
인지 부하	사람 — 뭐가 있고 언제 꺼낼지. 사람이 색인 노릇을 한다	⚠최소화 대상이 아니다

두 번째가 반직관적이다. 사람의 인지 부하는 줄여야 할 비용이 아니라 주체성의 값이라는 것. 판단이 필요한 자리에는 남기고, 아닌 자리에서만 없앤다.

여기서 나온 실무 규칙이 셋 더 있다.

점진적 공개는 토큰 최적화가 아니라 분산 레버다. 공개했어야 할 참조 자료를 본문에 두면 스텝이 파묻히고, 그 스텝에 주의가 가는 일이 동전던지기가 된다. 가독성이 아니라 편차의 문제다.

부정으로 조종하면 오히려 끌어온다. 금지된 행동이 컨텍스트로 들어와 더 접근 가능해진다 — “코끼리를 생각하지 마”, 그러면 코끼리밖에 없다. 부정은 약한 수식어라 강하게 활성화된 개념이 그걸 짓밟고, 금지가 절반쯤 지시로 읽힌다. 긍정 목표를 진술해서 금지된 쪽은 입에 올리지 않는 게 맞다.

no-op을 사냥한다. 모델이 기본값으로 이미 지키는 지시는 부하만 내고 아무 말도 안 한다. 판정 기준은 “기본값 대비 행동이 바뀌나”이고, 독자 기준이 아니라 모델 기준이다. 그래서 no-op이냐 아니냐로 두 사람이 다투면 그건 기본값에 대한 이견이고 — 토론이 아니라 문서를 실행해서 결판낸다.

완료 조건에 두 속성이 있다

에이전트가 “됐다/안 됐다”를 구분 못 하면 조기 완료가 일어난다. 진짜 끝나기 전에 끝내고, 주의가 ‘끝났음’ 쪽으로 미끄러진다.

속성	무엇
명료성	경계가 모호하면(“이해에 도달했다”) 조기 완료를 부른다. 경계를 먼저 날카롭게
요구도	“수정된 모든 모델이 설명될 것”은 철저함을 강제하고, “변경 목록을 만들어라”는 안 한다

가장 강한 기준은 확인 가능하면서 소진적인 것이다. 요구도는 별도 스텝으로 쓰이지 않고 문구에 잠복한다.

재본 결과 — 96개 중 1개

이 레포의 유일한 분류 축이 사용자호출 / 모델호출이다. 판정 질문 하나 — “모델이 이걸 자율적으로 집는 게 유용한가?”

	모델호출 (기본)	사용자호출
설명문	모델용 — 트리거 문구를 풍부하게	사람용 — 슬래시 목록에서 읽는 한 줄
부하	영구 컨텍스트 부하 ↔ 발견 가능성	컨텍스트 부하 0 ↔ 인지 부하
도달	모델 또는 사람 — 모델호출은 사람 접근을 포함한다	사람만

제 것에서 가장 선명한 사례가 하나 나왔다. 한 스킬의 설명문이 스스로 이렇게 쓰고 있었다 — “명시 호출 전용 — 일반 작업 중에 이해 확인 질문으로 사용자를 붙잡지 않는다.”

정책은 산문으로 선언돼 있는데, 하네스가 강제하는 플래그는 안 걸려 있다. Matt의 축으로 읽으면 이건 사용자호출 스킬을 모델호출로 배포한 것이다 — 모델이 집을 수 있는 상태로 두고 본문에 “집지 마”라고 쓴 셈이고, 위에서 본 부정 실패 모드가 정확히 이 모양이다. 플래그 한 줄이 그 산문 전체를 대체한다.

⚠ 그렇다고 96개 전부에 거는 건 오답이다. 상당수는 모델호출이 필수다 — 오케스트레이터가 부르는 파이프라인 스킬들이 그렇다. 축의 값어치는 전환이 아니라 96개를 그 질문으로 한 번 통과시키는 것이고, 걸기 전에 그 스킬을 부르는 에이전트·훅이 있는지 먼저 확인해야 한다.

안 가져온 것과 그 이유

플러그인 설치는 기각. 근거 넷이 전부 실측이다.

• 설명 25개가 상시 컨텍스트에 추가된다. 이미 95개가 무제한 로드 중인 환경에 얹는 건 저자 본인 교리에 정면 위배
• 중복 — TDD·코드리뷰·인계·리서치가 제 쪽에 이미 같은 역할로 있다
• 전제 불일치 — 엔지니어링 스킬 대부분이 특정 이슈트래커 배선을 요구하는데 제 실작업 도구엔 어댑터가 없다
• 언어 — 설명문이 영어라 한국어 발화에 대한 모델호출 적중률이 제 기존 스킬보다 낮다

대신 세 가지를 규율로 가져왔다. 「이건 안 한다」를 이유와 함께 못 박은 폴더를 두는 것(제 기각 목록은 지금 약어로만 살아 있어서 왜 기각했는지가 안 실려 있다), 리뷰를 두 축으로 나누되 병합·재랭킹을 금지하는 것(서식 지적이 커버리지 누락을 가리는 걸 막는다), 그리고 질문을 하나씩 왕복하지 말고 지금 물을 수 있는 것 전부를 한 라운드로 묶되 각각에 추천안을 붙이는 것.

마지막 것에 붙은 한 줄이 좋다 — “사실을 찾는 건 내 일이지 사용자 일이 절대 아니다. 내가 직접 찾아볼 수 있는 걸 사용자에게 묻지 마라. 결정은 사용자 것이다.”

반면교사도 있다

이 레포엔 테스트가 없다. 자동 검증은 플러그인 매니페스트 유효성 검사 정도고, 스킬 본문의 품질은 저자의 손 검증에 의존한다. *“문서를 실행해서 결판낸다”*는 교리가 있는데 그 실행이 CI에 없다. 이 축에서는 제 쪽이 앞선다 — 문서와 현실을 대조하는 린터 둘이 기계로 돌고 있다.

“프로세스를 소유하지 않는다”는 주장에도 반례가 있다. 상위 엔지니어링 스킬 몇은 이슈트래커 스키마·라벨 어휘·문서 배치를 상당히 규정한다. README가 때리는 경쟁자들과 정도의 차이지 종류의 차이는 아니다. 진짜로 “작고 조합 가능”한 건 생산성 버킷과 압박 질문 계열이다.

그리고 예제는 전부 웹·타입스크립트 편향이다. 가져올 건 어휘와 규율이지 예제가 아니다.