improve-codebase-architecture (mattpocock/skills)

리뷰

Codex CLI 0.166 (gpt-6-astra, low reasoning)을 전용 Windows 테스트 PC에서 실행했고, 실행마다 새 임시 프로젝트와 임시 HOME/TMPDIR/캐시를 사용했습니다. 스킬 설치(스킬 사용군), 미설치(대조군), 미설치 상태에서 스킬의 핵심 요구사항만 한 문장으로 압축해 프롬프트에 덧붙인 경우(한 문장 프롬프트군)로 나눴으며, 과제·그룹당 2회씩 실행했습니다. 네트워크는 끄고 /tmp 쓰기는 차단했습니다. 프롬프트에는 스킬 이름을 언급하지 않았습니다(아래에 적은 경우 제외). 마찰 요소를 심어 둔 작은 Python 쇼핑 백엔드에서 세 가지 과제를 수행했습니다(얕은 validator/금액 헬퍼, 저장소로 전달만 하는 재고 서비스, 결제 어댑터 하나뿐, 장바구니와 주문에 중복된 할인 로직, 헬퍼만 검증하는 테스트). 과제는 report.html로 작성하는 코드베이스 전체 아키텍처 리뷰, 같은 리뷰를 결제와 재고로 한정, 그리고 'place_order는 왜 테스트하기 어려운가'를 채팅으로 답하기입니다. 스킬 사용군의 프롬프트는 $improve-codebase-architecture로 시작하며(명시적 호출), 대조군과 한 문장 프롬프트는 스킬 이름을 언급하지 않습니다.

3개 그룹 비교

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

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

어떤 스킬인가

mattpocock/skills의 improve-codebase-architecture 스킬입니다. 코드베이스에서 '심화 기회'를 찾습니다. 인터페이스가 구현만큼 복잡한 얕은 모듈, 통과 전용 계층, 가정에 불과한 단일 어댑터 이음새, 중복 로직, 헬퍼를 통해서만 테스트되는 동작입니다. 후보별 전후 비교와 최우선 권고가 담긴 HTML 보고서를 작성합니다. 용어는 형제 스킬인 codebase-design에 기댑니다. Markdown만 사용하고 스크립트는 없습니다.

테스트 방법

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

심어 둔 마찰(얕은 검증기/금액 헬퍼, 자체 저장소로만 전달하는 재고 서비스, 결제 어댑터 하나, 장바구니와 주문에 중복된 할인 로직, 헬퍼만 검사하는 테스트)이 있는 작은 Python 쇼핑 백엔드에서 세 가지 작업을 수행했습니다. report.html로 작성하는 전체 코드베이스 아키텍처 리뷰, 결제와 재고로 범위를 좁힌 같은 리뷰, 그리고 'place_order는 왜 테스트하기 어려운가'를 채팅으로 답하는 작업입니다. 스킬군의 프롬프트는 $improve-codebase-architecture로 시작합니다(명시적 호출). 대조군과 한 문장 프롬프트는 이름을 언급하지 않습니다.

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

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

결과

세 번째 군에 전달한 한 문장 프롬프트: "심화 기회를 찾으세요. 인터페이스가 구현만큼 복잡한 얕은 모듈(삭제 테스트 적용: 삭제하면 복잡성이 한곳에 모이는가, 아니면 옮겨질 뿐인가?), 통과 전용 계층, 가정에 불과한 단일 어댑터 이음새, 여러 모듈에 중복된 로직, 실제 인터페이스가 아니라 헬퍼를 통해서만 테스트되는 로직입니다. 각 후보를 파일, 문제, 해결책, 이점, 전후 비교와 함께 제시하고 최우선 권고를 하나 지목하세요."

평균 점수: 스킬 없이 3.2, 스킬 사용 시 4.12(델타 +0.92). 실행당 토큰: 115k 대 208k(1.80배), 시간 112초 대 135초. 한 문장 프롬프트군: 3.91(한 문장 프롬프트 대비 스킬의 이득: +0.2, 스킬 없는 경우 대비 한 문장 프롬프트의 이득: +0.72). 한 문장 프롬프트는 실행당 120k 토큰을 쓰므로, 스킬은 한 문장 프롬프트의 1.73배 비용입니다.

실제로 있었던 일

• 전체 코드베이스 리뷰에서 차이가 드러납니다. 스킬과 한 문장 버전은 네 번의 실행 모두에서 아키텍처 용어, 전후 비교, 최우선 권고를 갖춰 6/6개의 심어 둔 포인트를 찾았습니다. 일반 Codex는 한 실행에서 2/6, 다른 실행에서 6개 검사 중 5개를 찾았고, 두 실행 모두 명확한 '최우선 권고'가 없었습니다.
• 범위를 좁힌 리뷰(결제와 재고만)는 모두에게 어렵습니다. 가장 좋은 군도 평균적으로 심어 둔 두 포인트 중 하나만 찾았습니다. 대조군 2/4 검사, 한 문장 3/4, 스킬 3/4. 스킬이 한 문장보다 더 잘하지는 못했습니다.
• 'place_order는 왜 테스트하기 어려운가'에서는 세 군 모두 심어 둔 원인(숨은 PaymentAdapter, 모듈 수준에서 공유되는 재고, 중복된 할인 로직, 헬퍼에서 멈추는 테스트)을 찾았습니다. 스킬의 답은 스킬 용어('interface', 'locality')를 사용했고, 대조군의 답은 평범한 말로 똑같이 정확했습니다.
• 평균 점수는 대조군 3.20, 한 문장 3.91, 스킬 4.12입니다. 스킬은 형제 스킬도 읽기 때문에 한 문장보다 토큰을 1.7배(실행당 208k 대 120k) 쓰면서 0.21점을 더합니다. 한 문장 프롬프트군은 대조군과 같은 비용(115k)입니다.
• 스킬이 스킬 폴더 두 개를 설치하므로 스킬 사용군은 프로젝트의 .agents 폴더에 추가 파일을 만들었습니다. 이 파일들은 '코드 파일 변경 없음' 검사에서 제외했습니다(첫 채점에서는 잘못 실패 처리되었고, 최종 수치 전에 검사의 Windows 관련 버그를 수정했습니다).

항목별 점수

이 테스트의 한계

• 교과서적인 심어 둔 문제가 있는 작은 Python 픽스처 하나입니다. 큰 실제 저장소에서 보고서가 유용한지는 측정하지 않았습니다.
• 보고서 품질, 오탐, HTML 스타일링(브라우저에서 열면 CDN에서 Tailwind와 Mermaid를 로드함)은 채점하지 않았습니다. 스킬이 설명하는 하위 에이전트 동작도 실행하지 않았습니다.
• 한 문장 프롬프트는 스킬 자체 체크리스트를 다시 진술한 것이므로, 짧은 프롬프트의 상한선입니다.
• 작업·군당 n = 2: 약 1점 미만의 차이는 노이즈입니다.
• 규칙 기반 채점은 검사가 볼 수 있는 것만 측정합니다. 취향이나 결과가 최선인지는 판단할 수 없습니다.

보안

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

결론

아무것도 하지 않는 것과 비교하면 이 스킬은 전체 코드베이스 리뷰를 분명히 개선하며, 주로 보고서 구조와 용어를 강제하기 때문에 토큰을 1.8배 씁니다. 같은 냄새를 나열한 한 문장만으로도 이득의 대부분을 얻으므로, 매번 동일한 보고서 형식을 원할 때 주로 설치할 가치가 있습니다.