데일리 밥

Agent Skills /review 와 /ship 쓰는 법 — 합치기 전 다섯 축 검토, 내보내기 전 체크리스트 [5/6]

Daily BaapIT/전자기기

혼자 만드는 프로젝트라 코드를 봐 줄 사람이 없는데, 합치기 전에 누가 한 번 봐 주면 좋겠다는 생각이 드시나요?

Agent Skills 의 /review 는 정확성·가독성·구조·보안·성능 다섯 축으로 변경을 훑고, 발견한 것을 「치명·중요·제안」 세 등급으로 파일 위치와 함께 내놓아요. /ship 은 한 단계 더 가요. 검토자·보안 감사자·테스트 엔지니어 에이전트 셋을 동시에 돌리고, 그 보고를 합쳐 GO / NO-GO 를 내요. 롤백 계획이 없으면 GO 가 안 나오게 만들어져 있어요.

이 시리즈 — ① 설치와 첫 확인 · ② /spec — 만들 것을 먼저 문서로 · ③ /plan — 일을 한 번에 끝낼 크기로 · ④ /build 와 /test · ⑤ /review 와 /ship(이 글) · ⑥ 알아서 켜지는 스킬과 한계

/review — 다섯 축, 그리고 「완벽」이 기준이 아니다

/review 는 code-review-and-quality 스킬을 불러요. 스킬 원문이 축마다 던지는 질문 몇 개를 옮기면 이래요.

축 묻는 것
정확성 사양대로인가, 빈 값·경계값·오류 경로를 다뤘나, 테스트가 정말 그걸 검사하나
가독성 다른 사람이 설명 없이 읽을 수 있나, 더 짧게 될 수 있나, 추상화가 값을 하나
구조 기존 패턴을 따르나, 의존 방향이 맞나, 복잡함을 줄였나 아니면 옮겼을 뿐인가
보안 입력 검증, 시크릿 노출, 인증·인가, SQL 매개변수화, 외부 데이터를 불신하나
성능 N+1 쿼리, 끝없는 반복, 목록에 페이지네이션이 있나

승인 기준이 눈에 띄어요. 「완벽하지 않아도 코드 건강을 확실히 좋게 하면 승인한다. 내가 썼을 방식과 다르다는 이유로 막지 않는다.」 저장소 README 는 이 플러그인이 구글의 엔지니어링 관행 문서를 많이 가져왔다고 소개하는데, 이 기준이 그 코드 리뷰 표준과 같은 문장이에요.

결과는 명령 정의(commands/review.toml)대로 치명(Critical)·중요(Important)·제안(Suggestion) 으로 나뉘고, 각 항목에 파일:줄 과 고치는 방법이 붙어요.

크기 이야기도 있어요. 변경 100줄이면 한 번에 볼 수 있고, 300줄은 한 가지 변경이면 괜찮고, 1,000줄은 쪼개라예요. 그리고 「문제만 말하지 말고 어떻게 옮길지 말하라」는 규칙이 있어요. 「복잡하다」로 끝내지 말고 「조건문 사슬을 타입 모델로 바꿔라」, 「공용 모듈에 새어 든 기능 로직을 그 기능 패키지로 옮겨라」처럼 이름 있는 처방을 내라는 거예요.

에이전트 넷 — 누가 보는가

이 플러그인에는 역할이 정해진 에이전트(페르소나) 넷이 들어 있어요.

  • code-reviewer — 시니어 스태프 엔지니어. 「스태프 엔지니어가 승인할 코드인가」 기준으로 다섯 축 검토
  • security-auditor — 보안 엔지니어. 취약점, 위협 모델, OWASP 상위 10개
  • test-engineer — QA. 테스트 전략, 빠진 케이스, 버그는 재현 테스트부터
  • web-performance-auditor — 웹 성능. Core Web Vitals. /webperf 명령 뒤에 있어요

docs/agents.md 가 세 층을 구분해요. 스킬은 「어떻게」(절차), 페르소나는 「누가」(관점과 보고 형식), 명령은 「언제」(둘을 묶는 입구). 그리고 규칙 하나 — 페르소나는 페르소나를 부르지 않아요. 묶는 일은 사용자나 명령이 해요.

/ship — 셋을 동시에 돌리고, 합치고, 결정한다

/ship 의 명령 정의(commands/ship.toml)는 세 단계예요.

A. 동시 실행. code-reviewer · security-auditor · test-engineer 셋을 한 턴에 동시에 띄워요. 순서대로 돌리면 이 명령의 의미가 없다고 적혀 있어요. 셋은 서로 대화하지 않고 각자 보고서만 돌려요.

B. 합치기. 메인 세션이 세 보고를 받아 여섯 묶음으로 정리해요. 코드 품질(검토자 + 테스트·린트·빌드 결과), 보안(감사자의 치명·높음은 출시 차단 요인으로 승격), 성능, 접근성, 인프라(환경변수·마이그레이션·모니터링·기능 플래그), 문서(README·ADR·변경 기록). 뒤의 셋 — 접근성·인프라·문서 — 은 에이전트가 안 보기 때문에 메인이 직접 확인해요.

C. 결정. 출력 틀이 정해져 있어요.

## Ship Decision: GO | NO-GO

### 차단 요인 (출시 전 반드시 고칠 것)
### 권고 (고치는 게 좋은 것)
### 감수하는 위험 (그래도 내보내는 것 + 완화책)
### 롤백 계획
- 되돌릴 조건: 어떤 신호가 보이면 되돌리나
- 되돌리는 절차: 정확한 단계
- 복구 목표 시간

규칙 다섯 개가 명령에 박혀 있어요. 셋은 병렬로 · 페르소나끼리 부르지 않는다 · 롤백 계획 없이는 GO 없다 · 치명 발견이 하나라도 있으면 기본은 NO-GO(사용자가 위험을 명시적으로 받아들일 때만 예외) · 변경이 2파일·50줄 이하이고 인증·결제·데이터·설정을 안 건드릴 때만 동시 실행을 생략할 수 있어요.

출시 체크리스트 — /ship 이 보는 목록

/ship 뒤의 shipping-and-launch 스킬 원문에 체크리스트가 있어요. 여섯 묶음에서 몇 개만 옮기면 이래요.

  • 코드 품질: 테스트·빌드·린트 통과, 남은 TODO 없음, console.log 없음
  • 보안: 시크릿 없음, 의존성 감사(npm audit 등)에 치명·높음 없음, CORS 가 와일드카드가 아님
  • 성능: Core Web Vitals 「좋음」, N+1 없음, 이미지 최적화, 번들 예산 안
  • 접근성: 키보드로 전부 조작 가능, 대비 4.5:1, axe·Lighthouse 경고 없음
  • 인프라: 환경변수, 마이그레이션, DNS·SSL, 헬스체크 엔드포인트
  • 문서: README, API 문서, ADR, 변경 기록

기능 플래그의 생애주기도 정해 두었어요. 플래그 OFF 로 배포 → 팀·베타에게만 켜기 → 5% → 25% → 50% → 100% → 전체 적용 2주 안에 플래그와 죽은 경로 제거. 플래그마다 담당자와 만료일이 있어야 하고, 플래그를 겹쳐 쓰지 말라는 규칙도 있어요.

같은 묶음의 두 명령 — /code-simplify 와 /webperf

/code-simplify 는 동작을 그대로 두고 복잡함만 덜어요. 깊은 중첩 → 조기 반환, 긴 함수 → 책임별로 나누기, 중첩 삼항 → if/else, 죽은 코드 제거. 한 번에 하나씩 고치고 매번 테스트를 돌리며, 테스트가 깨지면 그 변경만 되돌려요.

/webperf 는 웹 앱 전용이에요. Lighthouse JSON 이나 DevTools 추적 같은 측정 자료가 있으면 「깊은 모드」, 없으면 코드만 훑는 「빠른 모드」인데, 빠른 모드의 모든 발견에는 「잠재적 영향」 이라는 딱지가 붙어요. 재지 않은 지표를 숫자로 지어내지 않는다는 규칙이에요. CLI 나 라이브러리처럼 브라우저 화면이 없는 코드에는 쓰지 말라고 적혀 있어요.

안 되는 경우

  • 에이전트를 동시에 못 띄우는 환경이면 순서대로 돌아요. 명령 정의가 「서브에이전트를 쓸 수 없는 CLI 버전이면 세 페르소나를 메인에서 순차로 돌리고 병렬로 받은 것처럼 합쳐라」고 대비해 두었어요. 되긴 하지만 시간이 세 배예요.
  • 토큰이 많이 들어요. /ship 하나에 에이전트 셋이 각자 스킬을 부르고, code-review 스킬만 켜져도 7,000토큰이 넘어요(6편). 명령 자체가 「2파일·50줄 이하면 생략해도 된다」고 하는 이유예요.
  • 접근성·인프라·문서는 사람이 봐야 해요. 세 에이전트가 안 보는 영역이라 메인이 「직접 확인하라」고만 되어 있어요. 헬스체크가 있는지, 환경변수가 프로덕션에 들어갔는지는 결국 사람이 알아요.
  • 내가 만든 같은 이름의 에이전트가 있으면 그게 우선이에요. 프로젝트나 전역 설정에 code-reviewer 를 따로 정의해 두었다면 /ship 은 플러그인 것이 아니라 내 것을 써요. 의도된 동작이라고 적혀 있지만, 결과가 다르게 나올 때 헷갈리기 쉬워요.
  • /webperf 는 웹 앱에만. CLI·서버 전용 코드에는 볼 것이 없어요.

이럴 땐 쓰지 마세요

혼자 쓰는 스크립트, 배포되지 않는 실험 코드에 /ship 을 돌리면 롤백 계획과 모니터링을 묻는 질문만 돌아와요. 그런 코드에는 /review 하나로 충분해요. 그리고 검토 대상이 1,000줄을 넘으면 검토를 돌리기 전에 먼저 쪼개는 게 스킬의 권고예요. 큰 변경은 검토도 부실해져요.

✔ 요약

  • /review = 다섯 축 검토, 치명·중요·제안 + 파일:줄, 기준은 「코드 건강이 좋아지는가」
  • 에이전트 넷: 검토자·보안 감사자·테스트 엔지니어·웹 성능 감사자
  • /ship = 셋 동시 실행 → 여섯 묶음으로 합치기 → GO/NO-GO + 롤백 계획
  • 롤백 계획 없으면 GO 없음, 치명 하나면 기본 NO-GO
  • 기능 플래그는 OFF 배포 → 단계 확대 → 2주 안에 제거
  • 접근성·인프라·문서는 에이전트가 안 본다 — 사람이 확인
  • 2026년 9월 기준, 플러그인 버전 0.6.6

확인할 곳: code-review-and-quality 스킬 원문 · /ship 명령 정의 · shipping-and-launch 스킬 원문 · 에이전트 문서 docs/agents.md · 구글 코드 리뷰 표준

← 목록으로