Agent Skills 슬래시 명령과 Superpowers를 활용한 전체 수명주기 기능 제공

What they did

사용자는 기존 TypeScript 웹 앱에 작지만 실제적인 기능을 추가하고 싶었다. 바로 REST 엔드포인트, UI 토글, 영속성을 갖춘 저장된 검색(saved-search) 기능이었다. 임기응변식으로 에이전트에 프롬프트를 넣는 대신, 사용자는 마켓플레이스를 통해 Claude Code에 Agent Skills 플러그인을 설치했고, 브레인스토밍과 검증 워크플로를 위해 Superpowers도 추가했다. 사용자는 /spec으로 시작해 인터뷰 형식의 질문에 하나씩 답했고, 에이전트가 명시적인 비목표(non-goals)와 인수 기준(acceptance criteria)을 담은 짧은 PRD를 만들 때까지 진행했다. 그다음 /plan을 실행해 작업을 원자적 단위(스키마 마이그레이션, 엔드포인트, 클라이언트 훅, UI 토글, 테스트, 문서)로 나눴다. 빌드에 들어가기 전에 /constraints를 실행해 품질 기준을 확정했다. 승인 없는 새 의존성 금지, 새 모듈에 90% 커버리지, 타입이 지정된 API 계약이 그것이다. 사용자는 /build를 사용해 한 번에 한 슬라이스씩 구현했고, 에이전트는 먼저 실패하는 테스트를 작성한 뒤 각 작업을 개별적으로 커밋했다. nullable 컬럼에서 마이그레이션이 실패했을 때, 에이전트는 앞으로 밀어붙이지 않고 멈춰서 오류를 드러내고 수정안을 제안했다. 사용자는 /test를 실행해 스위트가 통과하는지 확인한 뒤, /review로 5축 코드 리뷰를 진행해 UI의 처리되지 않은 빈 상태(empty-state)와 새 테이블의 누락된 인덱스를 지적받았다. 이를 수정한 후 /code-simplify로 중복 헬퍼를 정리하고, /ship으로 체인지로그와 릴리스 체크리스트를 생성했다. Superpowers의 검증 단계는 병합 전에 실제 diff와 인수 기준을 대조해 확인하는 데 사용되었다.

How it went

이 기능은 깔끔한 커밋 이력과 함께 단 한 번의 오후에 완성되었고, 작업당 하나의 커밋, 그리고 새로운 엔드포인트와 훅을 커버하는 테스트 스위트를 갖추었다. 리뷰는 머지 전에 두 가지 실제 이슈를 잡아냈고, 제약 조건 파일 덕분에 예상치 못한 의존성이 끼어들지 않았다. 에이전트는 각 명령이 자체 컨텍스트를 한정했기 때문에 정해진 궤도에서 벗어나지 않았다. 작은 기능치고 완성도가 높았으며, 주요 마찰은 계획을 승인하는 것과 마이그레이션 수정 이후 몇몇 작업을 다시 실행하는 것이었다.

Worth knowing

스킬별 npx 설치 시 스킬 디렉터리만 복사되므로, 전체 저장소 설치나 클론을 하지 않으면 공유 references/ 체크리스트가 누락됩니다. /review 명령 이름은 Claude Code의 내장 명령과 충돌하므로 네임스페이스가 붙은 /agent-skills:review 형식을 사용해야 합니다. /build는 계획 승인 한 번 후 자율적으로 자동 실행되는데, 편리하긴 하지만 테스트 게이트를 켜 두고 위험한 단계를 주의 깊게 지켜봐야 합니다. 이 워크플로는 테스트 러너와 CI가 정상 동작하는 저장소를 전제로 하며, 그렇지 않으면 검증 단계가 수동 점검으로 저하됩니다.

Wiring

1) Claude Code에서 `/plugin marketplace add addyosmani/agent-skills`를 실행합니다(SSH 키가 설정되어 있지 않다면 HTTPS URL을 사용하세요). 그다음 `/plugin install agent-skills@addy-agent-skills`를 실행합니다. 2) Superpowers는 자체 설치 경로를 통해 추가하여 브레인스토밍 및 검증 스킬을 함께 사용할 수 있도록 합니다. 3) 슬래시 명령이 표시되는지 확인하세요. `/review`에는 `/agent-skills:review` 네임스페이스가 필요하다는 점을 기억하세요. 4) `/constraints`로 제약 파일을 생성하여 명령 전반에 걸쳐 품질 기준이 적용되도록 합니다. 5) `/spec`, 그다음 `/plan`, 그다음 `/build`를 실행합니다(또는 계획을 한 번 승인한 후 `/build`가 자동으로 실행되도록 합니다). 6) `/ship` 전에 `/test`와 `/review`를 게이트로 사용합니다. 스킬은 컨텍스트에 따라 자동으로 활성화되므로, API 설계와 프런트엔드 작업은 명시적으로 호출하지 않아도 관련 스킬을 불러옵니다.

Try it yourself

Claude Code용 Agent Skills 플러그인을 설치하고 Superpowers를 추가하겠습니다. 그런 다음 아래 기능에 대해 전체 라이프사이클을 실행하겠습니다: /spec으로 인수 기준과 비목표가 포함된 짧은 PRD 작성, /plan으로 원자적 작업으로 분해, /constraints로 품질 기준 확정(승인 없는 새 의존성 금지, 새 모듈에 테스트 필수, 타입이 지정된 API 계약), /build로 작업을 하나씩 테스트 우선으로 구현하고 작업당 커밋 하나, /test로 그린 확인, /review로 5축 리뷰, /code-simplify, /ship으로 체인지로그와 릴리스 체크리스트 초안 작성. 위험한 단계나 실패하는 테스트가 있으면 일시 중지하고 물어보겠습니다.

기능: REST 엔드포인트, 영속성, UI 토글을 포함한 저장된 검색(saved searches) 추가.

시작하기 전에 확인이 필요한 사항이 있습니다:

1. **플러그인 설치 및 Superpowers 추가** — 이 단계는 환경을 변경하므로, 진행하기 전에 확인 부탁드립니다. 설치를 진행할까요?

2. **기술 스택 확인** — 저장된 검색을 구현할 때 다음을 알아야 합니다:
   - 백엔드 언어/프레임워크 (TypeScript/Node? Python?)
   - 영속성 계층 (기존 DB가 있나요? 어떤 ORM/드라이버?)
   - 프론트엔드 프레임워크 (UI 토글을 어디에 둘지)
   - 기존 REST 엔드포인트 패턴

3. **"UI 토글"의 의미** — 저장된 검색을 켜고 끄는 기능인가요, 아니면 저장된 검색 목록을 표시/숨기는 토글인가요?

위 내용을 알려주시면 /spec부터 시작하겠습니다.