효과적인 에이전틱 코딩 (Agentic Coding)은 단순히 더 나은 프롬프트 (Prompt)에 관한 것이 아닙니다. 그것은 제어 (Control)에 관한 것입니다.

당신은 다음 세 가지를 동시에 원합니다:

• 극도로 빠르게 움직이는 것
• AI가 거의 모든 코드를 생성하게 하는 것
• 품질, 보안, 그리고 프로덕션 판단력을 인간의 통제하에 두는 것

명세 기반 개발 (Spec-driven development)은 이러한 긴장 상태를 유지하는 방법입니다. 더 강력한 에이전트 (Agents)는 생성 비용을 낮춰줍니다. 하지만 에이전트가 당신이 무엇을 원하는지, 무엇을 거부하는지, 또는 결과가 좋다는 것을 어떻게 알 수 있는지를 결정하지는 않습니다. 명세 (Specs)가 바로 제어 루프 (Control loop)입니다.

바이브 코딩 (Vibes Coding)이 실패하는 이유

모델이 충분한 구조 없이 코드를 작성할 때:

• 요구사항 (Requirements)이 모호한 상태로 남습니다.
• 트레이드오프 (Tradeoffs)가 명시되지 않은 채 남습니다.
• 제약 조건 (Constraints)이 생성 도중에 잊혀집니다.
• 팀은 올바른 답 대신 그럴듯해 보이는 첫 번째 답변을 배포하게 됩니다.

더 나은 자동 완성 (Autocomplete)과 더 나은 에이전트 (Agents)는 속도를 향상시킵니다. 하지만 이들이 공유된 의도 (Shared intent)를 만들어내지는 않습니다. 만약 당신의 팀이 생성이 시작되기 전에 무엇이 "완료 (Done)"를 의미하는지 지목할 수 없다면, 모델은 당신을 대신하여 추측하고 있는 것입니다.

생성을 마지막 단계로 만드세요

유용한 파이프라인 (Pipeline)은 다음과 같습니다:

1. 생각 쏟아내기 (Thought dump). 가공되지 않은 아이디어, 제약 조건, 엣지 케이스 (Edge cases), 그리고 미완성된 의견들을 포착합니다. 아직 구조를 강요하지 마세요.
2. 명확화 단계를 거친 PRD (PRD with clarification rounds). LLM이 몇 차례의 라운드를 통해 명확화 질문을 던지게 한 뒤, 쏟아낸 내용들을 제품 요구사항 문서 (Product Requirements Document)로 변환합니다.
3. 저장소 컨텍스트를 포함한 TRD (TRD with repo context). PRD를 코드 및 아키텍처 컨텍스트 (Architecture context)와 결합합니다. 다시 한번 명확히 합니다. 기술 요구사항 문서 (Technical Requirements Document)를 생성합니다.
4. 필요할 때 실험하기 (Experiments when needed). 설계 선택이 여전히 불확실할 때 벤치마크 (Benchmarks), 스파이크 (Spikes), 또는 비교를 수행합니다.
5. 단계별 구현 계획 (Phased implementation plan). TRD를 차곡차곡 쌓아 올릴 수 있는 작은 단계들로 나눕니다. 각 단계는 검토 가능하고 테스트 가능해야 합니다. 커밋(Commit)당 하나의 단계, PR(Pull Request)당 하나의 기능을 선호합니다.
6. 코드 생성 (Code generation). 오직 그 단계에서만 계획과 컨텍스트를 진실의 원천 (Source of truth)으로 삼아 구현을 생성합니다.

각 단계는 다음 단계가 신뢰할 수 있는 산출물 (Artifact)을 생성합니다. 모델은 생성 작업에 집중하고, 사람은 의도 (Intent)에 대한 책임을 유지합니다.

어려운 질문들을 조기에 강제하세요

명확화 단계 (Clarification rounds)는 단순히 더 깔끔한 문서를 만들기 위한 것이 아닙니다. 이는 누군가 이미 코딩을 시작하면 쉽게 건너뛰기 쉬운 질문들에 대해 팀이 답변하도록 만듭니다.

• 우리가 정확히 무엇을 만들고 있는가
• 우리가 만들지 않는 것은 무엇인가
• 규모가 커졌을 때(at scale) 어떤 일이 발생하는가
• 데이터 마이그레이션 (Data migration)은 어떻게 작동하는가
• 어떻게 배포(deploy)하는가
• 배포 후 어떻게 검증(verify)하는가
• 어떻게 롤백(roll back)하는가
• 보안 (Security)은 어떻게 처리되는가

이러한 질문들을 프로세스에 포함시키세요. 과거의 사고 사례와 리뷰에서 도출된 짧은 보안 체크리스트는 파이프라인이 이를 기대하도록 설계되었을 때 훨씬 더 효과적으로 작동합니다. 어색하게 느껴지던 체크 과정들이 선택 사항이 아닌 정상적인 절차가 됩니다.

두 번째 이점은 사람들이 파이프라인 과정 중에 학습한다는 것입니다. 코딩이 시작될 때쯤이면, 팀은 보통 처음 시작했을 때보다 문제를 더 잘 이해하게 됩니다.

컨텍스트의 제품화 (Productize Context)

모델이 참조할 안정적인 장소가 없다면 파이프라인은 실패합니다. 팀이 지목할 수 있는 마크다운 (Markdown) 문서를 유지하세요:

• 제품 및 기능 영역 (Feature areas)
• DB 스키마 (DB schemas)
• 서비스 및 소유권 경계 (Ownership boundaries)
• API 표면 (API surfaces)
• 컨벤션 (Conventions): 선호하는 방식, 피해야 할 방식, 이곳에서 정의하는 "좋은" 상태의 모습

코드의 형태 (Code shape) 또한 중요합니다. 거대한 파일은 컨텍스트 윈도우 (Context windows)와 싸우게 만들며 생성을 악화시킵니다. 더 작고 집중된 모듈은 인간과 모델 모두에게 에이전틱 코딩 (Agentic coding)을 더 사용하기 쉽게 만듭니다.

구현을 요청할 때는 명시적으로 지시하세요:

• 의존성 (Dependency) 변경 사항 포함
• 클래스 및 DB 스키마 변경 사항 포함
• 새로 추가되거나 업데이트된 라이브러리 명시
• 설계를 SOLID 원칙에 따라 테스트 가능하게 유지
• 테스트를 사후 고려 사항이 아닌 전달 (Delivery)의 일부로 취급

가장 힘든 작업은 프롬프트 엔지니어링 (Prompt craft)이 아닙니다. 그것은 컨텍스트를 작성하고, 생성이 어디서 벗어나는지 관찰하며, 컨텍스트를 다시 쓰고, 모델이 당신의 표준 내에 머물 때까지 이 과정을 반복하는 것입니다.

커밋하기 전에 불확실성 해결하기

모든 프로젝트에 스파이크 (Spike)가 필요한 것은 아닙니다. 하지만 어떤 프로젝트에는 반드시 필요합니다.

라이브러리, 플러그인 또는 접근 방식을 확정하기 전에 비교 분석을 요청하세요. 때로는 그것이 문서를 읽는 것일 수도 있고, 때로는 작은 벤치마크 (Benchmark)나 프로토타입 (Prototype)을 만드는 것일 수도 있습니다.

만약 설계가 미지의 요소 (Unknown)에 의존하고 있다면, 잘못된 경로에 전체 구현 사이클 (Implementation cycle)을 소비하기 전에 그 미지의 요소를 기록하고 먼저 해결하십시오. 확신이 없는 TRD (Technical Requirements Document)는 여전히 추측에 불과하다면 무용지물입니다.

도구가 변해도 중심축 (Spine)을 유지하라

내부 생성기 (Internal generators), Tab 완성 (Tab complete), 에이전트 (Agents): 표면은 계속해서 움직입니다. 그 아래의 동일한 중심축을 유지하십시오:

• PRD (Product Requirements Document)
• TRD (Technical Requirements Document)
• 필요 시 실험 (Experiments)
• 구현 계획 (Implementation plan)
• 단계별 실행 (Phased execution)

더 나은 에이전트는 더 긴 변경 사항을 실용적으로 만들어 줍니다. 하지만 에이전트가 명확한 계획을 대체할 수는 없습니다.

효과적인 에이전틱 코딩 (Agentic Coding)의 모습

1. 코드 이전에 명세 (Specs). 생각을 쏟아낸 다음, PRD와 TRD를 통해 명확성을 강제하십시오.
2. 풀 리퀘스트 (Pull requests) 이전에 단계 (Phases). 각 단계를 검토, 테스트 및 되돌리기가 가능할 만큼 충분히 작게 만드십시오.
3. 영리한 프롬프트 (Prompts) 이전에 컨텍스트 (Context). 스키마 (Schemas), 서비스 (Services), API, 그리고 컨벤션 (Conventions)을 문서화해야 합니다.
4. 마법 (Magic) 이전에 모듈형 코드 (Modular code). 집중된 파일들은 인간과 모델 모두에게 더 나은 환경을 제공합니다.
5. 확정 이전에 비교 (Comparisons). 불확실성을 설계 결정인 것처럼 가장하지 마십시오.
6. "좋아 보임" 이전에 체크리스트 (Checklists). 확장성 (Scale), 마이그레이션 (Migration), 배포 (Deploy), 롤백 (Rollback), 그리고 보안 (Security)은 선택적인 추가 사항이 아닙니다.
7. 판단은 인간의 몫. 모델은 생성하고, 사람은 결정합니다.

에이전틱 코딩은 사람들이 모델을 진실의 근원 (Source of truth)으로 취급할 때 실패합니다. 반면, 사람들이 모델을 명확하고 테스트 가능한 계획 안에서 작동하는 매우 빠른 구현자 (Implementer)로 취급할 때 성공합니다. 명세 (Specs)는 바로 그 경계를 유지하는 방법입니다.

저는 2023년부터 2025년까지 BlogVault에서 AI 코딩 에이전트를 사용하여 제품을 출시하며 이 사실을 어렵게 깨달았습니다. 저는 더 이상 그곳에 있지 않으며, 이 글은 회사의 공식 문서가 아닙니다. 저는 dharmiq를 포함한 저의 개인적인 작업에서도 여전히 동일한 패턴을 사용합니다: 제품 의도를 명확히 하고, 기술 요구 사항을 작성한 다음, 작성된 원칙과 계획에 따라 단계별로 구현하는 것입니다.