에이전트는 이미 워크플로우 안에 있다—문제는 '구조'가 없다는 것
속도는 올라갔다. 코드는 빠르게 나온다. 그런데 커밋 로그는 여전히 fix, update, wip으로 가득하고, 프로덕션에서는 엣지 케이스가 터진다. AI를 '챗봇'처럼 쓰고 있기 때문이다. 도구가 아니라 워크플로우에 구조적으로 박혀야 비로소 품질이 올라간다. 최근 dev.to에 올라온 세 편의 글—Claude 기반 코드 감사 스킬 interruptions, Claude Code slash command /commit, 그리고 40년 경력 시니어 아키텍트의 'Clean AI Development' 매니페스토—은 각자 다른 레이어에서 같은 문제를 풀고 있다. 커밋 단계, 리뷰 단계, 설계 단계. 세 레이어를 묶으면 팀 워크플로우에 에이전트를 심는 하나의 실용적 청사진이 된다.
레이어 1: 커밋부터 정리된다—slash command /commit
가장 가까운 레이어부터 보자. Claude Code의 slash command는 마크다운 파일 하나가 곧 명령어가 되는 구조다. ~/.claude/commands/commit.md에 파일을 두면 /commit이라는 슬래시 커맨드가 생긴다. DSL도, SDK도, 플러그인 매니페스트도 없다. 마크다운 파일 하나가 전부다.
브라질 개발자 Guilherme가 공개한 /commit 구현은 단순하지만 영리하다. 핵심은 에이전트에게 git status 파싱을 맡기지 않는다는 점이다. 대신 bin/commit-survey라는 22줄짜리 Ruby 스크립트가 변경 파일을 config, test, db, app, docs 버킷으로 미리 분류한다. 에이전트는 분류된 결과만 읽고 Conventional Commits 형식으로 그룹별 커밋을 만든다. .env나 시크릿 파일은 skip 버킷으로 자동 제외된다.
결과물이 의미하는 바가 있다. 같은 변경을 update 하나로 뭉개던 것이 feat(blog): add slash commands post, chore(config): drop syntax theme, style(sass): apply osaka jade palette 세 개의 정제된 커밋으로 쪼개진다. 30초 안에. 그리고 이 규칙은 팀 전체가 동일하게 적용받는다. 규칙을 마크다운 파일에 한 번 써두면, 금요일 오후의 피곤한 개발자도 월요일 아침과 같은 품질의 커밋을 남긴다. 이게 슬래시 커맨드의 진짜 가치다—개인 생산성 도구가 아니라 팀 품질 기준선의 코드화.
레이어 2: 프로덕션 전에 막는다—Claude 감사 스킬 interruptions
커밋이 깨끗해졌다면, 다음 문제는 그 코드 안에 숨어 있는 엣지 케이스다. 결제 중 전화 한 통, 업로드 도중 네트워크 끊김, 두 탭이 동시에 같은 폼을 제출하는 상황. 이런 것들은 코드 리뷰로는 잘 안 잡힌다. 이미 만든 사람이 리뷰하면 자신이 놓친 가정을 똑같이 가지고 있기 때문이다.
Omraj가 공개한 interruptions는 이 문제를 12개의 구조화된 실패 카테고리로 접근한다. UX 심리, 보안(IDOR·재전송 공격·프론트엔드 변조), 상태 일관성, 네트워크 장애, 동시성 경쟁 조건, 결제 무결성, 접근성, 입력 검증, 에러 복구까지. npx skills add omrajguru05/interruptions 하나로 Claude Code·Desktop·Claude.ai 전체에 활성화된다.
스킬의 설계 철학에서 주목할 부분은 확인 게이트(confirmation gate)다. 감사 결과가 interruptions-audit.md에 기록된 뒤, Claude는 다음 단계를 스스로 진행하지 않는다. 개발자가 직접 읽고 확인을 주기 전까지 멈춘다. 결제 경로나 인증 로직처럼 고위험 코드를 에이전트가 이해도 없이 수정하면 나중에 역엔지니어링해야 하는 상황이 생긴다. 이 '기다리는 설계'가 단순한 UX 배려가 아니라 팀 안전의 핵심 장치라고 보는 이유다. 수정 단계에서도 에이전트는 최소 diff만 적용하고, 기존 테스트가 실패하면 테스트를 수정해서 통과시키는 대신 즉시 중단한다.
레이어 3: 에이전트를 길들이는 설계 원칙—Clean AI Development
두 레이어가 전술적 도구라면, 세 번째는 전략적 방법론이다. 40년 경력의 시니어 아키텍트가 공개한 'Clean AI Development'는 에이전트를 쓸 때 생기는 근본 문제를 7개 원칙으로 정리한다.
핵심만 추리면 이렇다. 아키텍처 주권: 인터페이스·DTO·API 계약을 먼저 정의하고, 에이전트는 그 경계 안에서만 로직을 채운다. 에이전트가 아키텍처를 결정하게 두면 장기 유지보수를 잃는다. 의미 분리: 프론트엔드·백엔드·DB 컨텍스트를 한 세션에 섞으면 '컨텍스트 오염'과 환각이 생긴다. 도메인별로 세션을 분리한다. 상태 없는 세션 관리: todo.md로 진행 상태를 추적하고, 세션이 포화되면 새 세션을 시작해 최신 TODO를 주입한다. 컨텍스트가 오염되기 전에 체크포인트를 만드는 것이다.
BMAD 프로토콜(Brief·Minimalist·Accurate·Direct 또는 Briefing·Modeling·Architecture·Delivery)이 실용적이다. 코드를 짜기 전에 요구사항 재확인 → 인터페이스/DTO 정의 → 수정할 파일 목록 제시 → 개발자 승인 후에야 구현 시작. 승인 없이 구현으로 넘어가면 해당 작업은 실패로 간주한다. 이 프로세스가 interruptions의 확인 게이트, /commit의 버킷 분류와 같은 맥락임을 볼 수 있다. 에이전트가 혼자 결정하게 두지 않는다는 원칙이 세 도구 모두에 일관되게 흐른다.
시사점: 품질 자동화의 3단 레이어를 팀에 이식하는 법
세 접근을 하나의 흐름으로 보면 이렇게 된다. 설계 단계에서 Clean AI 원칙으로 아키텍처 경계를 먼저 정의하고, 개발 과정에서 에이전트가 경계 안을 채운다. 커밋 시점에 /commit slash command가 변경을 의미 단위로 분리해 기록한다. 배포 전에 interruptions 스킬이 12개 카테고리로 엣지 케이스를 스캔하고, 개발자가 직접 확인한 뒤 수정이 진행된다.
도입 순서는 팀 상황에 따라 다르겠지만, 가장 저항이 적은 진입점은 slash command다. 마크다운 파일 하나, 팀 프로젝트 레포에 .claude/commands/commit.md를 올리는 것으로 시작할 수 있다. 설치 비용이 거의 없고, 효과는 다음 커밋부터 즉시 보인다. 이후 코드베이스 복잡도가 올라갈수록 interruptions 감사를 PR 전 체크리스트에 붙이고, 팀이 안정되면 Clean AI 원칙을 CLAUDE.md나 시스템 프롬프트로 공식화하는 순서가 현실적이다.
전망: 에이전트 통제선의 표준화
세 사례가 공통적으로 보여주는 방향이 있다. 에이전트의 자율성을 높이는 게 아니라, 개발자가 검토하고 승인하는 구조적 멈춤(structured pause)을 설계하는 쪽으로 진화하고 있다는 것이다. interruptions의 확인 게이트, BMAD의 승인 단계, slash command의 명시적 규칙 파일—모두 에이전트가 더 많이 하도록 두는 게 아니라, 에이전트가 하는 것을 개발자가 이해하고 통제할 수 있게 만드는 장치다.
팀 규모가 커지고 에이전트 활용도가 높아질수록, 이 통제선을 개인의 프롬프트 습관이 아니라 팀 인프라 수준으로 표준화하는 팀이 품질을 지킨다. 마크다운 파일 하나짜리 slash command가 팀 전체의 커밋 기준선이 되는 것처럼, 감사 스킬과 설계 원칙도 결국 팀 레포에 버전 관리되는 표준으로 올라와야 한다. 에이전트를 빠르게 쓰는 팀은 많아졌다. 구조적으로 심은 팀은 아직 드물다.