AI 코딩 에이전트는 기본적으로 스펙 작성, 테스트, 코드 리뷰, 범위 규율 같은 중요한 단계를 건너뛴다. Google Chrome팀 엔지니어링 디렉터 Addy Osmani가 이 문제를 해결하기 위해 정리한 5가지 원칙이다.

“시니어 엔지니어의 일은 대부분 diff에 보이지 않는 부분들이다. 스펙. 테스트. 리뷰. 범위 규율. 검증할 수 없는 것은 배포하지 않는 자세. AI 코딩 에이전트는 이 부분들을 기본적으로 건너뛴다.”

에이전트는 코드를 빠르게 생성하지만, 시니어 엔지니어가 당연히 하는 작업들을 생략한다. 이 5가지 원칙을 에이전트 스킬로 만들면 이 격차를 메울 수 있다.

5가지 원칙

1. Process over prose (프로세스 우선)

에세이가 아니라 워크플로가 필요하다. 에이전트에게 200페이지 핸드북을 읽히는 것은 의미가 없다. 체크포인트가 있는 작은 워크플로 세트만 에이전트가 실제로 실행한다.

팀 핸드북도 마찬가지다. 시간 압박 상황에서 사람도 200페이지는 안 읽는다. 에이전트도 다르지 않다.

적용: 규칙을 글로 쓰지 말고, 에이전트가 실행할 수 있는 절차로 만들어라.

2. Spec-first (스펙 우선)

코딩 전에 스펙을 먼저 작성하도록 에이전트에 강제한다. 스펙 없이 코딩하는 에이전트는 “뭔가 그럴듯한 것”을 만들지, “원하는 것”을 만들지 않는다.

적용: 에이전트 워크플로에 스펙 작성 단계를 반드시 포함하라.

3. Verification is nonnegotiable (검증 필수)

모든 스킬은 구체적 증거로 끝나야 한다. 테스트 통과, 빌드 클린, 런타임 트레이스 확인, 리뷰어 승인. “그럴 것 같다”는 충분하지 않다.

“에이전트는 생성기(generator)다. 작업이 끝났다는 별도의 신호가 필요하다. 스킬은 그 신호를 모든 워크플로에 내장한다.”

Anthropic 에이전트 하네스, Cursor의 planner/worker/judge 분리, 장기 실행 에이전트 모두 이 원칙 위에 작동한다.

적용: 에이전트 루프에 독립적인 검증 단계를 넣어라.

4. Review before ship (배포 전 리뷰)

에이전트가 만든 코드도 반드시 리뷰를 거쳐야 한다. 에이전트는 빠르게 생성하지만, 리뷰 없이 배포하면 기술 부채가 빠르게 쌓인다.

적용: 에이전트 PR도 사람의 리뷰 단계를 건너뛰지 않도록 워크플로를 설계하라.

5. Scope discipline (범위 규율)

“요청받은 것만 건드려라.” 연관 시스템을 리팩터링하지 말고, 완전히 이해하지 못한 코드를 제거하지 말고, TODO 옆을 지나다가 파일 전체를 재작성하지 마라.

“범위 규율은 에이전트 PR이 병합 가능한가를 결정하는 가장 큰 요소다. Google의 코드 리뷰 규범과도 가장 잘 맞는 원칙이기도 하다.”

적용: 메타 스킬로 “요청받은 것만 건드린다”를 에이전트에게 주입하라.

스킬로 만드는 방법

이 5원칙을 SKILL.md에 넣어 에이전트에 주입한다:

# coding-quality

## 언제 사용하나
모든 코딩 작업 전

## 프로세스
1. [ ] 스펙 작성: 무엇을 만들어야 하는가?
2. [ ] 테스트 먼저: 구현 전 실패 테스트 작성
3. [ ] 구현
4. [ ] 검증: 테스트 통과, 빌드 클린 확인
5. [ ] 범위 확인: 요청받은 것만 건드렸는가?

Addy Osmani의 웹 품질 관련 구체적인 스킬 구현체는 addyosmani/web-quality-skills에서 참고할 수 있다.

참고 자료

• Agent Skills — O’Reilly Radar, Addy Osmani (2026-05-27)