하루에 14개 기능을 혼자 구현했다는 이야기는 솔직히 처음 들으면 과장처럼 들린다. 그런데 dev.to에 공개된 OneSlate 빌드 로그를 보면, 숫자보다 그 구조가 더 인상적이다. Claude로 전략을 짜고, cowork 에이전트로 구현하고, 실기기로 검증하는 3레이어 협업 패턴. 속도는 이 구조의 결과물이지, 목적이 아니었다.
그런데 이 성공 사례에는 6시간짜리 실패가 숨어 있다. postcss.config.mjs 파일 하나가 없어서 프로덕션 CSS가 2.1KB로 쪼그라들었고, AI 에이전트는 이 사실을 몇 주 동안 한 번도 확인하지 않은 채 Tailwind 클래스를 열심히 써댔다. 에이전트는 프로젝트의 '가정'을 검증하지 않는다. 주어진 환경 안에서 최선을 다할 뿐이다.
이 한 장면이 AI 코딩 에이전트를 둘러싼 구조적 문제를 정확하게 드러낸다. dev.to의 또 다른 분석 글이 이를 체계적으로 해부한다. AI가 설계 의도대로 코딩하지 못하는 원인은 모델 성능이 아니라 세 가지 구조적 공백 때문이라는 것이다. 첫째, 팀의 암묵적 컨벤션은 AI에게 전달되지 않는다. 둘째, 스펙 문서는 '무엇을'은 설명하지만 '어떻게'와 '왜'는 담지 않는다. 셋째, 인간 코드 리뷰가 만드는 피드백 루프가 AI 생성 코드에서는 작동하지 않는다. AI가 컨벤션을 어겨도, 다음 세션엔 다시 처음부터다.
이 공백이 누적되면 단순한 스타일 불일치가 아니라 아키텍처 일관성 붕괴로 이어진다. 에러 핸들링 패턴이 파일마다 다르고, 인증 미들웨어가 엉뚱한 레이어에 놓이고, 스키마가 컴포넌트 파일 안에 섞인다. 리뷰어는 AI 지원으로 3배 빨라진 PR 속도를 따라잡지 못하고, 컨벤션 드리프트는 조용히 쌓인다. 문제는 AI가 나쁜 코드를 쓰는 게 아니라, 그럴듯하지만 틀린 코드를 쓴다는 점이다.
해법의 핵심은 '더 좋은 프롬프트'가 아니다. AI가 항상 접근할 수 있는 지식의 집을 설계하는 것이다. OneSlate 빌더가 200~400줄짜리 구현 프롬프트를 만들 수 있었던 건 Claude와의 전략 대화가 먼저 있었기 때문이고, Claude Code를 실전에 도입한 백엔드 개발자가 소개한 방식은 이를 한층 체계화한다. 프로젝트 루트의 CLAUDE.md는 단순한 README가 아니다. AI가 코드를 생성할 때마다 자동으로 참조하는 하네스(Harness) — 설계자가 쳐둔 기술적 울타리다.
실전에서 효과적인 컨텍스트 설계는 세 층위로 구성된다. 첫 번째는 도메인 지식 문서화다. docs/design/db-schema.md, docs/api/ 같은 구조로 복잡한 기획을 마크다운으로 정제해두면, AI는 일일이 설명하지 않아도 데이터 관계와 도메인 경계를 파악한다. 두 번째는 규칙 레이어 분리다. .claude/rules/ 아래 layers.md(컨트롤러-서비스-레포지토리 참조 규칙), exception.md(공통 에러 포맷), dto.md(변환 로직 가이드)처럼 규칙을 파일 단위로 세분화하면, AI는 코드를 생성할 때마다 이를 참조해 일관된 스타일을 유지한다. 세 번째는 컨텍스트 노이즈 제거다. .claudeignore로 빌드 파일과 node_modules를 걸러내고, 복잡한 기획 문서를 requirements.md로 압축해 AI가 핵심 비즈니스 로직에만 집중하게 만드는 것이다.
여기에 하나를 더 얹는다면 AI-effective 스펙 작성 방식이다. 전통적인 스펙은 '인증된 사용자가 프로필을 수정할 수 있어야 한다'고 쓴다. AI가 읽어야 하는 스펙은 다르다. auth()는 @/lib/auth에서, 허용 필드는 name과 image만, 입력 검증은 Zod 스키마로, 응답 포맷은 { data: user } 또는 `{ error: "...