AI 코딩 툴이 설계대로 구현하지 않는 구조적 이유
ADF로 설계서를 재정의하고, 개발자의 경험으로 품질을 시스템화하라
"설계서를 줬는데 왜 이상하게 짜지?"
이 한 마디가, AI 코딩 시대의 가장 보편적인 좌절입니다.
Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 어시스턴트가 빠르게 확산되면서, 많은 개발자들이 공통된 벽에 부딪히고 있습니다. 설계서를 그대로 넘겨도 원하는 코드가 나오지 않는다. 더 세세하게 지정할수록, 오히려 해석의 괴리가 벌어진다.
이 문제의 근본 원인은 설계서 자체의 구조적 한계에 있습니다. 기존의 설계서는 "인간의 암묵지" -경험에서 축적된 판단 기준, 팀 내 불문율, 도메인 특유의 문맥 - 를 전제로 작성됩니다. 하지만 AI에게는 그 맥락이 존재하지 않습니다.
세세한 지시가 오히려 역효과를 내는 이유도 여기에 있습니다. 지시가 많아질수록, AI는 그 지시들 사이의 우선순위와 맥락을 스스로 추론해야 하고, 그 과정에서 개발자의 의도와 점점 멀어집니다.
본 강좌에서는 이 구조적 문제를 해부하고, 해결책으로서 'ADF(Agentic Development Framework)' 라는 개념을 제안합니다.
ADF란?
ADF(Agentic Development Framework)는, 개발자의 설계 사상/판단 기준/코딩 규칙을 계층적으로 체계화한 "개인 개발 기반(Personal Development Foundation)"입니다.
스마트폰의 운영체제가 그 위에서 동작하는 모든 앱에 공통 기반(메모리 관리, 입출력, 파일 시스템)을 제공하듯이, ADF는 프로젝트를 가로질러 "개발의 공통 기반"을 제공합니다.
프로젝트가 바뀌어도, 팀원이 교체되어도, 사용하는 AI 툴이 달라져도 - 개발자의 판단 기준과 품질 기준은 일관되게 유지됩니다.
이것은 단순한 .cursorrules 파일(또는 Cursor Rules)이나 프롬프트 모음집이 아닙니다. 개발자의 사고방식 자체를 AI가 해석 가능한 구조로 변환하는 프레임워크입니다.
이 강좌에서 다루는 내용
문제 분석
왜 설계서를 AI에게 넘겨도 의도한 대로 되지 않는가 - 구조적 원인의 해부
AI가 "잘못 해석"하는 것이 아니라, 처음부터 맥락이 공유되지 않은 상태에서 작동하고 있다는 사실
지시를 세세하게 쪼갤수록 오히려 품질이 떨어지는 역설
AI와의 협업 전략
프로젝트 규모(개인 / 소규모 팀 / 대규모 조직)에 따라 최적의 AI 협업 방식이 다른 이유
한국 개발 현장에서 자주 쓰이는 애자일/스크럼 프로세스와 AI 코딩 툴의 접점
설계서(Spec)보다 룰과 가이드라인이 AI에게 더 효과적으로 작동하는 이유와 메커니즘
ADF 설계 방법
4계층 구조: 사상(Philosophy) → 원칙(Principles) → 가이드라인(Guidelines) → AI 사고 프레임(AI Thinking Frame)
각 계층의 역할과 작성 방법
역산 어프로치: 원하는 코드 결과물로부터 필요한 규칙을 역방향으로 도출하는 방법론
실제 프로젝트에서 바로 쓸 수 있는 가이드라인 템플릿 예시
실제 적용 방법
Git Submodule을 활용한 AI Dev OS의 프로젝트 적용 방법
개인 자산(개인 Dev OS)과 팀 공유 자산의 경계를 어떻게 설계할 것인가
Cursor의 .cursorrules, Claude Code의 CLAUDE.md등 각 툴과의 연동 방법
CI/CD 파이프라인에서 가이드라인 준수를 자동으로 검증하는 구조
대상 독자
AI 코딩 툴(Claude Code, Cursor, GitHub Copilot 등)을 도입했지만, 생성되는 코드의 품질이나 일관성에 의문을 느끼는 엔지니어
기획/설계 단계에서 충분히 생각했는데도, AI 구현 결과물이 기대와 다른 경험을 반복하고 있는 분
프리랜서/1인 개발자로서, 여러 프로젝트를 오가면서도 품질 기준을 유지하고 싶은 분
스타트업 CTO, 테크 리드로서 팀 전체의 AI 코딩 품질을 끌어올릴 구조를 찾고 있는 분
"프롬프트를 잘 짜면 해결된다"는 접근에 한계를 느끼기 시작한 분
이 강좌에서 다루지 않는 것들
특정 툴(Cursor, Claude Code 등)의 설치 방법이나 초기 설정 절차
"이 프롬프트를 쓰면 된다"는 식의 즉석 기법 모음
특정 언어(Python, TypeScript 등)나 프레임워크에 특화된 코딩 규칙
본 강좌는 툴의 사용법이 아닌, AI와 협업하는 개발 구조 자체를 어떻게 설계할 것인가를 다룹니다.
목차
1. 설계서 한계와 AI 협업의 올바른 접근법
2. 프로젝트 규모별 AI 코딩 협업 전략 - 소규모/대규모에서 설계 산출물을 어떻게 달리해야 하는가
3. AI 코딩에서 설계서보다 룰이 강한 이유 - 품질 일관성을 시스템화하는 룰 설계 완전 가이드
4. ADF란 무엇인가 - 개발자의 판단 기준을 4계층으로 체계화하는 AI 개발 프레임워크 완전 가이드
5. ADF를 실제 프로젝트에 적용하는 방법 - Git Submodule/CLAUDE.md/팀 공유까지 실전 완전 가이드
6. AI 코딩 시대의 개발 패러다임 전환 - 설계서 중심에서 룰 중심으로, ADF가 개인 자산이 되는 이유
ADF Architecture
©2024-2026 MDRules dev., Hand-crafted & made with Jaewoo Kim.
이메일문의: jaewoo@mdrules.dev
AI강의/개발/기술자문, AI 업무 자동화 컨설팅 문의: https://talk.naver.com/ct/w5umt5
AI 프롬프트 및 워크플로우 설계 대행: https://mdrules.dev