Swift 개발자가 Next.js 경험 없이 3일 만에 풀스택 앱을 출시했다. Claude Code를 쓴 덕분이다. 그런데 이 이야기의 핵심은 'AI가 코드를 써줬다'가 아니다. 핵심은 에이전트에게 일을 시키는 방식이다. 같은 도구를 써도 어떻게 지시하느냐에 따라 결과물의 품질과 속도가 완전히 달라진다.
코드 먼저 달라고 하지 마라
dev.to에 올라온 실전 후기에서 Swift 개발자 kangsw1025는 첫 번째 실수를 솔직하게 고백한다. Google OAuth와 Turso DB 스키마를 바로 구현해달라고 했더니 동작은 했지만 조각들이 맞지 않았다. 인증 흐름이 DB 스키마와 충돌했고, 통합 지점을 처음부터 다시 설계해야 했다.
그가 찾은 해법은 단순하다. 코드 전에 설계 문서를 먼저 요청하는 것이다. "이 기능의 아키텍처, 데이터 흐름, 에러 처리 전략, API 계약을 설계해줘. 내가 검토하고 승인하면 구현하자." 이 한 줄의 순서 변경이 이후 구조적 재작성을 제로로 만들었다.
현장에서 테크 리드로서 이 부분을 강하게 공감한다. AI는 지시받은 범위 안에서만 생각한다. 설계 없이 구현을 먼저 요청하면 AI는 '지금 이 코드가 다른 코드와 어떻게 맞물리는지' 모른 채 최선의 로컬 솔루션을 만들어낸다. 비용이 가장 큰 실수는 200줄을 쓴 뒤에 발견된다.
에이전트는 자기가 쓴 코드를 제대로 리뷰하지 못한다
같은 글에서 두 번째 교훈이 더 날카롭다. 동일한 AI 세션에 방금 작성한 auth 코드를 리뷰해달라고 했더니 사소한 제안만 돌아왔다. 그런데 새 세션을 열고 '코드 리뷰어' 역할을 부여한 뒤 같은 코드를 건네자 즉시 세 가지 구조적 문제를 잡아냈다. OAuth 콜백의 누락된 에러 핸들러, any 타입 남용, 검증되지 않은 세션 체크.
같은 코드, 다른 관점, 완전히 다른 결과. 이유는 명확하다. 코드를 생성한 세션은 그 코드를 쓸 때와 동일한 맹점을 갖고 있다. 생성과 검증을 분리하는 '크로스 세션 패턴'은 선택이 아니라 품질 관리의 기본 조건이다.
우리 팀 워크플로우에서도 이 원칙을 적용한다. AI가 작성한 코드를 AI로 리뷰할 때는 반드시 별도 컨텍스트를 주고 역할을 명시한다. 같은 모델이라도 역할 프레임이 다르면 다른 관점에서 텍스트를 처리한다.
Rules File, 지금 당장 반 이상 지워라
에이전트 설정 파일 이야기를 빼놓을 수 없다. ETH Zurich의 2026년 2월 연구가 불편한 사실을 공개했다. LLM이 생성한 Rules File은 작업 성공률을 3% 떨어뜨리고 비용은 20% 올렸다. 인간이 직접 작성한 Rules File도 성공률은 4% 올리지만 비용이 19% 증가했다.
dev.to의 Alex Efimenko는 수천 개의 Rules File을 직접 분석한 뒤 규칙을 네 등급으로 분류했다. Essential(필수): 에이전트가 코드나 설정 파일에서 스스로 발견할 수 없는 정보. Helpful(유용): 여러 파일을 뒤져야 겨우 알 수 있는 것. Redundant(중복): tsconfig.json이 있는데 "TypeScript를 써라"고 적은 것. Improve Codebase(도구가 할 일): no-var ESLint 규칙으로 강제할 수 있는데 AI에게 지시한 것.
그가 분석한 전형적인 28개 규칙짜리 파일에서 15개가 Redundant 또는 Improve Codebase였다. 절반 이상이 노이즈. 그는 11개로 줄였고, 모든 줄이 에이전트의 실제 행동을 바꿨다.
컨텍스트 윈도우는 싸울 자리가 아니다
왜 이게 중요한가. LLM의 컨텍스트 윈도우는 Rules File, 대화 이력, 코드 컨텍스트, 에이전트 자신의 추론이 모두 공유하는 고정 공간이다. "TypeScript를 사용해라"라고 적힌 줄은 tsconfig.json이 이미 전달하는 정보를 토큰으로 낭비한다. 그리고 LLM은 긴 컨텍스트의 중간 부분에 주의를 덜 기울인다('lost in the middle' 효과). 정작 중요한 규칙이 노이즈에 묻힌다.
감사 기준은 세 가지 질문으로 충분하다. 첫째, 설정 파일에서 이미 알 수 있는 정보인가? 그렇다면 삭제. 둘째, 린터나 CI로 강제할 수 있는가? 그렇다면 도구로 이동. 셋째, 이 규칙을 없애면 에이전트가 틀린 결정을 내리는가? 그렇다면 필수, 최대한 구체적으로 작성. "에러를 적절히 처리해라"는 무의미하다. "서비스 함수에서는 try-catch 대신 neverthrow Result 타입을 사용해라"는 동작을 바꾼다.
에이전트를 잘 쓴다는 건 결국 '무엇을 넘기느냐'의 문제다
세 소스를 겹쳐보면 하나의 패턴이 나온다. AI 에이전트 활용의 병목은 대부분 도구의 성능이 아니라 지시의 품질에서 온다.
코드 생성량이 폭발하는 시대에 '무엇을 만들지'는 AI가 점점 더 많이 담당한다. 그러나 '어떤 설계로, 어떤 제약 안에서, 어떤 기준으로 검증할지'는 여전히 인간이 정의해야 한다. Swift 개발자가 3일 만에 풀스택 앱을 출시할 수 있었던 이유는 AI가 뛰어나서가 아니라, 그가 설계 주도권을 놓지 않았기 때문이다.
팀에 바로 적용할 수 있는 세 가지
지금 당장 내일 팀 워크플로우에 넣을 수 있는 것만 추린다.
첫째, 구현 요청 전 설계 문서를 먼저 받아라. 프롬프트 템플릿을 하나 만들어서 팀에 공유하라. "구현하기 전에 아키텍처, 데이터 흐름, 에러 처리 전략을 먼저 작성해줘. 내가 검토 후 구현 승인하겠다."
둘째, CLAUDE.md나 .cursorrules를 지금 열고 각 줄에 세 가지 질문을 던져라. 설정 파일로 알 수 있나? 도구로 강제할 수 있나? 없애면 에이전트가 틀린 결정을 내리나? 절반은 오늘 지울 수 있다.
셋째, AI 생성 코드를 AI로 리뷰할 때는 반드시 별도 세션과 명시적 역할을 써라. "방금 작성한 코드의 보안 취약점과 구조적 문제를 찾아라"는 같은 세션에서는 생성할 때와 동일한 맹점을 가진 채 동작한다.
에이전트 시대의 역량은 '얼마나 많이 생성하느냐'가 아니다
Anthropics CEO의 '6개월 내 90% AI 코드' 예측이 화제가 됐지만, 현재 수치는 약 41%다. 그러나 궤적은 분명하다. 코드 생성량은 폭발하고, 그 코드를 이해하지 못한 채 머지하는 개발자는 더 느리게 디버깅하고 더 큰 리스크를 안는다.
에이전트를 잘 쓰는 능력은 프롬프트 스킬이 아니라 시스템적 사고에 가깝다. 무엇을 AI에게 위임하고, 무엇을 인간이 통제하며, 어디서 검증 루프를 설계할지. 그 판단이 팀의 생산성과 코드 품질을 결정한다. AI가 코드를 쏟아내는 속도가 빨라질수록, 그 흐름을 설계하는 사람의 가치는 올라간다.