codebase-design (mattpocock/skills)

리뷰

Codex CLI 0.166 (gpt-6-astra, low reasoning)을 전용 Windows 테스트 PC에서 실행했고, 실행마다 새 임시 프로젝트와 임시 HOME/TMPDIR/캐시를 사용했습니다. 스킬 설치(스킬 사용군), 미설치(대조군), 미설치 상태에서 스킬의 핵심 요구사항만 한 문장으로 압축해 프롬프트에 덧붙인 경우(한 문장 프롬프트군)로 나눴으며, 과제·그룹당 2회씩 실행했습니다. 네트워크는 끄고 /tmp 쓰기는 차단했습니다. 프롬프트에는 스킬 이름을 언급하지 않았습니다(아래에 적은 경우 제외). 작은 쇼핑몰 백엔드에 여섯 가지 마찰 지점을 심어 두었습니다(얕은 검증자와 금액 래퍼, 그대로 전달만 하는 재고 서비스, 단일 결제 어댑터, 중복 로직 등). 과제는 아키텍처 개선 사항을 담은 HTML 보고서 작성, 결제와 재고로 범위를 한정한 보고서 작성, 그리고 'place_order는 왜 테스트하기 어렵고 어떻게 고치겠는가'에 답하기(채팅으로 응답)입니다. 프롬프트에는 어떤 설계 용어도 언급하지 않았습니다. 한 문장 프롬프트군은 깊이에 대한 개념과 짚어야 할 항목을 제시합니다.

3개 그룹 비교

Codex CLI에서 18회 실행해 측정했고, LLM 심사 없이 규칙 기반 검사로 채점했습니다. 총점 23.6 / 30, 판정 상황에 따라.

판정: 상황에 따라 (23.6 / 30). 출처: mattpocock/skills, skills/engineering/codebase-design, 커밋 4ae2317에 고정. 설치: npx skills@latest add mattpocock/skills --skill codebase-design. 라이선스: MIT(저장소 LICENSE).

무엇인가

mattpocock/skills의 codebase-design 스킬입니다. 모듈의 깊이를 기준으로 아키텍처를 리뷰하는 방법을 제시합니다. 깊은 모듈은 작은 인터페이스 뒤에 많은 동작을 숨깁니다. 얕은 통과형 모듈, 가정에 불과한 단일 어댑터 이음새, 중복 로직, 헬퍼를 통해서만 테스트되는 동작을 지적하고, 동작을 인터페이스로 테스트할 수 있도록 이음새가 어디에 있어야 하는지 알려 줍니다.

테스트 방법

Codex CLI 0.166(gpt-6-astra, 낮은 추론)을 전용 Windows 테스트 PC에서 실행했고, 실행마다 새 임시 프로젝트와 임시 HOME/TMPDIR/캐시를 사용했습니다. 스킬을 설치한 스킬 사용군, 스킬이 없는 대조군, 스킬 없이 핵심 요구사항을 한 문장으로 압축해 프롬프트 끝에 붙인 한 문장 프롬프트군으로 나눴으며, 작업·군당 2회 실행, 네트워크 차단, /tmp 쓰기 차단 조건이었습니다. 프롬프트에는 스킬 이름을 전혀 언급하지 않았습니다(아래에 적은 표현 제외).

마찰 지점 여섯 개를 심어 둔 작은 쇼핑 백엔드입니다(얕은 검증기와 금액 래퍼, 통과형 재고 서비스, 단일 결제 어댑터, 중복 로직 등). 작업은 아키텍처 개선점을 담은 HTML 보고서 작성, 결제와 재고로 범위를 한정한 보고서 작성, 'place_order는 왜 테스트하기 어렵고 어떻게 고치시겠습니까'(채팅으로 답변)입니다. 프롬프트에는 어떤 설계 용어도 등장하지 않습니다. 한 문장 프롬프트에는 깊이 개념과 지적해야 할 항목이 적혀 있습니다.

1. 저장소 전체 아키텍처 스캔 — 이 작은 쇼핑 백엔드에서 아키텍처 개선점을 찾아주세요. 구조를 바꾸면 코드를 더 쉽게 변경하고 더 쉽게 테스트할 수 있는 곳은 어디인가요? 결과를 이 폴더의 report.html이라는 독립형 HTML 보고서로 작성하세요(브라우저를 열거나 서버를 시작하지 마…
2. 결제와 재고만 — 이 백엔드의 결제와 재고 부분만 살펴보고 어떤 구조 변경이 효과를 볼지 알려주세요. 결과를 이 폴더의 report.html이라는 독립형 HTML 보고서로 작성하고(브라우저를 열거나 서버를 시작하지 마세요), 어떤 코드도 변경하지 마…
3. place_order는 왜 테스트하기 어려운가? — 이 백엔드에서 place_order에 제대로 된 테스트를 작성하는 것은 고통스럽게 느껴집니다. 왜 그렇고, 어떤 구조 변경이 이를 해결할까요? 파일은 변경하지 말고 최종 메시지로 답하세요.

채점은 프로그램 방식(숨은 테스트/심어 둔 문제 탐지/제약 조건 검사/해당되는 경우 렌더링+OCR)으로 진행하며 실행당 0~5점입니다. 어떤 점수도 LLM 심사자가 결정하지 않았습니다.

결과

세 번째 군에 제공한 한 문장 프롬프트: "모듈을 깊이로 판단하세요. 깊은 모듈은 작은 인터페이스 뒤에 많은 동작을 숨깁니다. 얕은 통과형 모듈, 가정에 불과한 단일 어댑터 이음새, 중복 로직, 헬퍼를 통해서만 테스트되는 동작을 지적하고, 동작을 인터페이스로 테스트할 수 있도록 이음새가 어디에 있어야 하는지 밝히세요."

평균 점수: 스킬 없음 3.21 vs 스킬 사용 3.92(델타 +0.71). 실행당 토큰: 119k vs 133k(1.12배), 시간 154초 vs 158초. 한 문장 프롬프트군: 4.54(한 문장 프롬프트 대비 스킬의 이득: -0.63, 스킬 없음 대비 한 문장 프롬프트의 이득: +1.34). 한 문장 프롬프트는 실행당 114k 토큰이므로 스킬 비용은 한 문장 프롬프트의 1.17배입니다.

무슨 일이 있었나

• 대조군 3.21, 스킬 3.92, 한 문장 4.54(각 6회). 안내가 없을 때 HTML 보고서는 아키텍처 용어를 거의 쓰지 않았습니다(deep/shallow/seam/interface 사용 0~2회, 검사 기준은 6회). 보고서를 낸 실행 4회 중 4회 모두 그랬습니다. 스킬 보고서는 4회 모두 이 용어를 사용했고 한 문장 프롬프트도 마찬가지였습니다.
• 백엔드 전체 스캔: 스킬 4.24와 3.41, 한 문장 3.41과 3.86, 대조군 2.88과 2.2. 안내를 받은 두 군 모두 심어 둔 문제 6개 중 3~4개를 찾았습니다. 얕은 검증기 래퍼와 단일 결제 어댑터는 모든 군에서 여러 실행에 걸쳐 놓쳤습니다.
• 결제·재고에 집중한 작업: 스킬은 두 실행 모두 3.75, 대조군은 두 실행 모두 2.5, 한 문장은 두 실행 모두 5.0이었습니다. 스킬과 대조군의 모든 실행은 두 지점 중 하나만 찾았습니다(가정에 불과한 단일 결제 어댑터를 놓침). 한 문장 프롬프트는 둘 다 찾았습니다.
• place_order 테스트 난이도: 모든 군이 비슷했습니다(대조군 4.17과 5.0, 스킬 4.17과 4.17, 한 문장 5.0과 5.0). 스킬 실행은 한 번은 원인 하나(헬퍼 전용 테스트)를, 다른 한 번은 통과형 계층을 놓쳤습니다.
• 토큰: 실행당 스킬 133k, 한 문장 114k, 대조군 119k(대조군의 1.12배). 스킬은 스킬 사용군 6/6 실행에서 읽혔습니다.

항목별 점수

이 테스트의 한계

• 보고서 텍스트에 대한 규칙 기반 탐지 검사(파일 이름 근처 키워드)와 용어 개수 집계입니다. 제안된 구조 변경이 타당한지는 판단하지 않았고 보고서를 브라우저에서 열어 보지도 않았습니다.
• 용어 검사는 스킬 자체의 용어에 점수를 주는데, 한 문장 프롬프트도 같은 용어를 언급하므로 안내를 받은 군에 유리합니다.
• '전후' 검사는 스캔 작업에서만 2회 실패로 나타났으며 차별 요소가 아닙니다.
• 셀당 n=2, 작은 코드베이스 하나.
• 작업·군당 n=2: 약 1점 미만의 차이는 노이즈입니다.
• 규칙 기반 채점은 검사가 볼 수 있는 것만 측정하며, 취향이나 결과가 최선인지는 판단하지 못합니다.

보안

security.md를 참고하세요. 스캔: CRITICAL 0 / HIGH 0 / MEDIUM 0. 판정: 실행해도 안전(네트워크 차단 샌드박스). 깨끗한 스캔 결과가 스킬의 안전성을 증명하지는 않습니다.

결론

이 스킬은 아무것도 주지 않은 프롬프트에 없는 모듈 깊이라는 관점을 리뷰에 분명히 부여하며 대조군보다 점수가 조금 높습니다. 그러나 같은 개념을 한 문장으로 적으면 더 적은 토큰으로 심어 둔 문제를 더 많이 찾습니다. 따라서 이득은 대부분 표현 방식에 관한 것입니다.