요즘 유행처럼 AI 코딩 에이전트 정말 많이들 쓴다.
나도 처음엔 그냥 생산성이 올라가는 게 신기해서 열심히 썼다.
탐색도 빨라지고, 반복 작업도 줄어들고, 손대기 귀찮았던 일들이 훨씬 가벼워졌다.
근데 좀 지나니까 다른 게 보이기 시작했다.
내가 다루던 서비스는 비슷해 보이는 화면이 여러 도메인으로 나뉘어 있고, 운영 정책도 많고, "여긴 이렇게 하면 안 됨" 같은 숨은 규칙도 꽤 있었다. 코드만 보고는 절대 다 알 수 없는 구조였다.
AI는 코드를 빨리 만들어줬지만, 정작 중요한 맥락은 자꾸 빠졌다.
프롬프트를 더 잘 쓰면 해결될 줄 알았는데, 계속 써보니까 그건 절반만 맞는 말이었다.
진짜 문제는 프롬프트가 아니라,
에이전트가 어떤 순서로 생각하고, 무엇을 먼저 확인하고, 어디서 멈춰야 하는지가 없다는 거였다.
결국 난 "AI를 잘 쓰는 법"을 찾는 것보다, "AI가 일하는 방식"을 설계하는 일에 집중을 하였다.
시작은 "동료가 있었으면" 하는 마음
나는 특정 도메인의 백오피스 프론트엔드 개발을 혼자 맡는 경우가 많았다.
물론 팀은 있었지만,, (육휴,, 인력부족,,,)
실제 코드 작업에서는 혼자 판단하고 혼자 커밋하는 시간이 꽤 많았다.
그러다 보면 가끔 이런 생각이 들었다.
"옆에 믿음직한 동료가 한 명 있으면 어떨까?"
내가 놓친 걸 잡아주고, "야 이거 정책 함수 영향 있는데?" 하고 먼저 말해주고, 코드 치기 전에 "이 방향 맞아?" 하고 같이 확인해주는 그런 동료.
그런 동료를 AI로 만들어보면 어떨까 — 가 출발이었다.
당연히 그냥 붙여놓기만 하면 그런 동료가 되지는 않았다.
실무에서는 코드 작성보다 더 앞단의 일이 중요할 때가 많다.
이 티켓이 진짜 뭘 바꾸는 건지, 비슷한 구현이 이미 있는지, 이 변경이 정책 함수까지 건드리는지, 커밋 전에 뭘 다시 확인해야 하는지 같은 것들.
사람도 자주 놓치는 걸 AI라고 알아서 챙길 리가 없었다.
그래서 생각이 바뀌었다.
코드 생성부터 시키지 말고, 작업의 시작과 끝을 먼저 고정하자.
작업의 시작과 끝을 먼저 고정하기 — /start와 /done
제일 먼저 만든 건 개별 프롬프트가 아니라 워크플로우였다.
/start에서는 티켓을 읽고, 피그마를 통해 디자인이나 화면 맥락을 보고, 관련 코드를 탐색하고, 작업 복잡도를 판단하고, 필요하면 서브태스크로 쪼개게 했다.
/done에서는 diff를 다시 읽고, 정책 키워드를 탐지하고, 테스트 전략을 확인하고, 품질 게이트 통과 여부를 보고, 그 다음에야 커밋이나 MR로 넘어가게 했다.
물론, 각 커맨드에서 티켓 상태변경을 잊지않았다.
이걸 만들고 나서 체감이 확 왔다.
예전엔 에이전트가 바로 코드를 치는 느낌이었다면, 그 다음부터는 먼저 맥락을 읽고 나서 움직이는 느낌이 강해졌다.
코드를 치기 전에 "이거 먼저 확인해야 하지 않아?" 하고 물어보는 — 바로 내가 바라던 그 동료의 모습이었다.
결국 필요한 건 사고 모델
/start와 /done으로 작업의 양 끝을 잡고 나니, 그 사이를 채울 사고 흐름이 필요해졌다.
나는 에이전트가 일을 시작하자마자 바로 구현으로 뛰어들지 않았으면 했다.
그래서 COT(Chain-of-Thought) 그리고 장인의 인지적 도제 이론(Cognitive Apprenticeship)에서 힌트를 얻었다.
사람이 전문가에게 배울 때도 바로 실행부터 하는 게 아니라 먼저 관찰하고, 모방하고, 직접 해보고, 되돌아보는 과정을 거친다.
그래서 에이전트도 이런 똑같은 과정을 6단계에 거치도록 했다.
작은 수정이면 짧게 통과하고, 영향 범위가 넓으면 분석 단계를 더 가져가고, 정책 함수나 위험한 변경이면 검증 강도를 올리고, 마지막엔 "내가 범위를 넘지 않았는지" 돌아보게 하는 구조였다.
이 흐름이 들어가니까 에이전트가 무작정 빠르게만 움직이지 않게 됐다.
규칙이 많을수록 에이전트가 똑똑해지는 건 아니었다
6단계 모델은 방향은 맞았는데, 계속 쓰다 보니 두 가지 문제가 보였다.
첫째, 너무 무거웠다. thinking-model 외에도 release-readiness-gate.md, required-behaviors.md, sequential-thinking.md까지 따로 만들어뒀었는데, 에이전트가 규칙 문서를 읽는 데만 토큰의 상당 부분을 소비했다.
문서가 많을수록 에이전트가 똑똑해지는 게 아니라, 컨텍스트 윈도우만 빨리 차는 거였다.
둘째, 모든 작업에 동일한 6단계를 적용하게 되어 있어서, 파일 하나 고치는 간단한 수정에도 ANALYZE, RESTRUCTURE를 거치는 비효율이 있었다.
그래서 3+1단계로 줄였다.
GROUND → APPLY → VERIFY, 실패하면 ADAPT가 붙는 구조.
GROUND → APPLY → VERIFY
↑ ↓
└─── ADAPT ←──────┘ (실패 시만)그리고 핵심 철학은 한 문장으로 압축했다.
"코드베이스가 스승 — 기존 코드에는 보이지 않는 이유가 있을 수 있다."
여러 파일에 흩어져 있던 규칙들은 5가지 불변 제약(읽기 우선, 패턴 준수, 정책 보존, 최소 변경, 스코프 준수)으로 압축해서 4개 파일 수백 줄을 1개 파일 99줄로 만들었다. 작업 규모에 따라 S/M/L로 분기시켜서, 파일 하나짜리 수정은 GROUND 후 바로 APPLY로 넘어가게 했다.
인지적 도제 이론의 "관찰 → 모방"을 더 극단적으로 밀어붙인 셈이다.
규칙을 줄줄이 알려주는 대신, "먼저 읽고, 관찰한 패턴을 따르라"는 원칙 하나로 대체한 것.
100개의 규칙보다 1개의 올바른 원칙이 더 강력했다.
이 변화 이후로 규칙을 로드하는 데 쓰던 토큰이 절반 이하로 줄었고, "어디서 뭘 읽어야 하지?" 같은 혼란도 사라졌다.
워크플로우 체계화와 6단계 인지 모델을 처음 설계했던 배경, 원래 구조들이 궁금하다면 이전에 사내 블로그에 정리한 글을 참고하면 된다.
규칙은 문서가 아니라, 실제로 작동해야 함
또 하나 느낀 건, 팀 규칙이 문서에만 있으면 금방 증발한다는 거였다.
상태 관리 경계, 날짜 계산 규칙, 테스트가 꼭 필요한 케이스, 하면 안 되는 패턴, 리뷰에서 반복되는 피드백…
위키에만 있으면 사람도 놓치고, 에이전트도 놓친다.
최근 "하네스(Harness)" 개념에 대한 글을 읽었는데 딱 이거랑 맞닿아 있었다. LLM이라는 강력한 엔진이 있어도, 그걸 제어하고 맥락을 주입하는 인프라가 없으면 실무에서 쓸 수가 없다.
규칙을 문서가 아니라 "에이전트가 실행 시점에 자동으로 로드하는 코드"로 만들어야 했다.
그래서 공통 에이전트, 공통 스킬, 팀 코드 룰, 커밋 규칙, 협업 룰 같은 범용적인 것들은 한 레포에서 관리하고, 각 프로젝트에서는 profiles/로 도메인 차이만 올리는 식으로 정리했다.
공통과 개별을 섞지 않는 게 핵심이었다.
만능 에이전트 하나보다, 역할을 나누는 쪽이 훨씬 안정적
처음엔 이것저것 다 잘하는 에이전트 하나를 기대하게 된다.
근데 실무에서는 그게 오히려 더 위험했다.
탐색, 분석, 구현, 검증을 따로 나눠놓으면 누가 무엇을 하는지 보이고, 어디까지 수정 가능한지 선이 생기고, 실수했을 때 영향 범위도 줄어든다.
처음에 "옆에 동료가 있었으면" 하고 바랐던 게, 결국은 역할이 나뉜 작은 팀을 만드는 방향으로 갔다.
그래서 최종적으로는 에이전트들을 단순한 프롬프트가 아니라 "작업 시스템"처럼 구성하게 됐다.
정리하면 현재 cms-agents 구조는 다음과 같다.
cms-agents/
├── CLAUDE.md # 진입점 — 전체 규칙/에이전트/스킬 허브
├── .claude/
│ ├── agents/ (14종) # 전문 에이전트 (READ-ONLY + READ-WRITE + Git + Codex)
│ ├── skills/ (11종) # 재사용 가능 워크플로우 (start, done, debate 등)
│ ├── rules/core/ (5종) # 코딩 규칙 (thinking-model, coding-standards 등)
│ ├── instructions/ # 오케스트레이션 + 품질 게이트 + 협업 룰
│ └── profiles/ # 프로젝트별 커스텀 오버라이드에이전트를 READ-ONLY(분석 전용)와 READ-WRITE(수정 가능)로 나눈 것도 중요했다. 코드 리뷰 에이전트가 실수로 코드를 수정하거나, 탐색 에이전트가 파일을 건드리는 일이 없도록 도구 수준에서 권한을 잘랐다.
다만 에이전트가 많다고 좋은 것도 아니었다.
처음엔 code-reviewer랑 security-reviewer를 따로 뒀는데, 쓰다 보니 모델도 같고 도구도 같고 차이는 체크리스트뿐이었다. reviewer 하나에 mode: quality | security | both로 통합했고, testgen(팀 공용 테스팅 패키지)/로컬 테스팅 가이드/테스팅 에이전트도 하나로 합쳤다.
"어떤 에이전트를 써야 하지?"라는 고민 자체가 비용이다.
에이전트 수를 줄이면서 선택이 아닌 설정의 문제로 바뀌었다.
정리하고 보니 이건 프롬프트 모음집이라기보다 "팀이 AI랑 일하는 방식"을 묶어둔 운영 레이어에 더 가까웠다.
사내 블로그에 올린 뒤,,
이 내용을 사내 블로그에 올리고 나니까 다른 팀에서 연락이 꽤 왔다.
재밌었던 건 질문들이 거의 비슷했다는 점이다. 다들 비슷한 데서 막혀있었다.
"그렇게 복잡하면 진짜 빨라져?"
빨라졌다.
적어도 운영성 작업이나 중간 정도 복잡도의 기능 수정에서는 확실히 체감됐다.
API URL 바뀌어서 타입 추가하고, 필드 하나 더 붙이고, 관련 화면 몇 군데 수정하고, 정책 함수 영향 확인하고, 테스트 포인트 챙기는 정도
— 이런 작업은 /start 붙이고 서브에이전트 같이 돌리는 게 훨씬 빨랐다.
Agent Teams까지 같이 쓰면 예전엔 엄두도 안 났던 대규모 수정도 가능해졌다. 물론 그만큼 토큰은 빨리 쓴다.(디지털 월세...)
좋은 구조를 만든다고 공짜로 빨라지는 건 아니다.
속도는 구조 + 모델 + 플랜 + 작업 분해 방식이 다 같이 영향을 준다.
나 같은 경우는 Max 플랜을 꽤 빡세게 쓰는 편이고, 주변엔 더 높은 플랜 쓰는 분들도 있었다.
결국 "어느 정도까지 병렬로 굴릴 건가"에 따라 체감이 꽤 달라진다.
"매번 커스텀하면 결과가 흔들리지 않아?"
솔직히 완전히 안 흔들린다고는 못 한다.
근데 내가 커스텀하게 만든 부분은 대부분 원래 달라질 수밖에 없는 부분들이었다. 프로젝트별 코드 컨벤션, 도메인별 금지 규칙, 특정 정책 함수 예시 같은 것들.
오히려 범용 레이어에는 예시를 너무 많이 넣지 않으려고 했다. 예시가 많아질수록 특정 프로젝트 색이 짙어지고, 다른 레포로 옮길 때 더 꼬이기 때문이다.
공통 쪽(rules/core/)은 최대한 범용적으로 두고, 진짜 달라질 수밖에 없는 부분만 profiles/로 커스텀.
완벽한 재현성은 아니어도, 실무에서 감당 가능한 수준의 일관성을 유지하는 쪽에 가까웠다.
"MCP는 어디까지 붙였어?"
필요한 것만 붙였다.
디자인 맥락 확인이 중요해서 피그마 쪽은 연결해두고, 나머지는 안 될 때 대비해서 스크립트로 우회 가능한 형태를 준비해두는 식이었다.
실무에서는 "완벽한 연결"보다 "안 되면 다른 길로라도 되게 하는 것"이 더 중요할 때가 많다.
안 되면 되게 해야 했다. 그게 제일 컸다.
아직 남아 있는 문제
물론 지금 구조가 완벽한 건 아니다.
현재는 공통 레포를 @import해서 버전 관리되는 구조라기보다, 에이전트에게 공용 레포를 참고하게 하고 프로젝트에 맞게 커스텀하는 식이라 버전 관리가 깔끔하지 않다.
그래서 다음 단계를 고민하고 있다. 팀 내 플러그인 마켓플레이스 체계로 전환하면서, upstream 변경 시 downstream에 자동 PR을 보내는 구조, rules/core/는 auto-merge하고 profiles/는 수동 리뷰로 나누는 충돌 정책 같은 것들을 설계 중이다.
끝난 구조라기보다는 지금도 계속 다듬고 있는 구조에 가깝다.
확실히 알게 된 건..
AI 코딩 에이전트를 쓰면서 느낀 건 하나였다.
에이전트에게 필요한 건 더 많은 자유가 아니라 더 좋은 사고 과정이라는 점이다.
좋은 결과는 좋은 모델도 중요하지만, 그 모델이 어떤 기준 안에서 움직이게 하느냐가 실무에서는 훨씬 중요했다.
모델은 점점 더 좋아질 것이다.
하지만 어떤 순서로 읽고, 무엇을 먼저 확인하고, 어디까지 수정하고, 어디서 멈춰야 하는지는 결국 사람이 설계해야 한다.
나는 그걸 "AI를 잘 쓰는 법"이라고 부르기보다는 "AI와 같이 일하는 방식"이라고 생각한다.
아마 앞으로도 더 똑똑한 에이전트를 만드는 것보다는 여러 프로젝트에서 안정적으로 굴러가는 작업 시스템을 계속 다듬는 쪽을 더 파게 될 것 같다.
