AI 코딩 에이전트를 처음 써본 사람이라면 누구나 비슷한 경험을 한다. 처음 며칠은 마법처럼 코드가 뚝딱 생성되다가, 어느 순간부터 똑같은 실수가 반복되기 시작한다. catch 블록에는 아무 로그도 없고, any 타입이 슬금슬금 끼어들고, API 응답 구조가 요청마다 들쭉날쭉해진다. 이건 AI의 문제가 아니다. 워크플로우 설계의 문제다.
에이전트에게 '컨텍스트'를 주는 가장 저렴한 방법: .cursorrules
dev.to에 공유된 한 SaaS 개발자의 사례는 이 문제를 정확히 짚는다. 그는 Node.js + TypeScript 프로젝트에서 Cursor를 사용하며 반복적으로 같은 코드 품질 문제를 수정해야 했다. 그가 선택한 해결책은 단순했다. 프로젝트 루트에 .cursorrules 파일을 두는 것. npm install도, 별도 설정도 필요 없다. AI가 실제로 읽고 따르는 스타일 가이드를 코드베이스 안에 심어두는 방식이다.
이 접근의 핵심은 '교정'이 아니라 '예방'이다. 매번 잘못된 코드를 고치는 대신, 처음부터 올바른 패턴으로 생성되도록 경계를 설정한다. 에러 핸들링 방식, 타입 정책, 환경변수 사용 규칙 같은 팀 컨벤션을 AI가 기억하게 만드는 것이다. 작은 파일 하나가 에이전트의 '행동 규범'이 된다.
복잡한 프로젝트일수록, 코드보다 문서가 먼저다
싱글 스택 프로젝트라면 .cursorrules만으로도 충분할 수 있다. 하지만 Python CLI + React/Remotion 같은 멀티스택 프로젝트에서는 다른 차원의 설계가 필요하다. dev.to에 공개된 ShortsMaker 프로젝트 사례(gpt-5-codex 활용, 4커밋 부트스트래핑)는 이 문제에 대한 명확한 답을 제시한다: 코드 작성 전에 아키텍처를 설계하라.
핵심 원칙은 AI에게 첫 번째로 PROJECT_BRIEF.md와 ARCHITECTURE.md를 작성하게 하는 것이다. 코드 생성 요청을 하기 전에 전체 그림을 문서화하면, AI는 이후 모든 작업에서 이 문서를 일관된 참조 프레임으로 사용한다. "사주 비디오 앱 만들어줘" 대신 기술 제약, 입출력 스펙, 디렉토리 구조, 그리고 '하지 말아야 할 것들'까지 명시한 구조적 프롬프트가 필요하다. 안티패턴을 미리 차단하는 것이다.
에이전트를 믿지 말고, 검증하게 하라
프로젝트가 커질수록 AI는 조용히 방향을 잃는다. 이를 막는 가장 효과적인 방법은 단계마다 체크포인트 검증 프롬프트를 심는 것이다. ShortsMaker 사례에서는 각 커밋 단위로 AI 스스로 자신의 출력을 검증하도록 요청했다. 1단계에서는 pip install -e .과 npm install이 실제로 작동하는지, 순환 의존성은 없는지를 확인시킨다. 2단계에서는 샘플 데이터로 엔드투엔드 파이프라인을 직접 테스트하게 한다.
이 패턴의 본질은 'AI를 코드 생성기가 아닌, 출력에 책임지는 엔지니어처럼 다루는 것'이다. Claude Code의 /commit과 /review 명령어를 단순 커밋 메시지 생성이 아니라 논리적 작업 단위 검증 도구로 활용하는 방식도 같은 맥락이다.
컨텍스트 관리가 멀티스택 프로젝트의 성패를 가른다
Python과 TypeScript를 동시에 다루는 프로젝트에서 AI가 가장 자주 실패하는 지점은 언어 전환 시 컨텍스트를 잃는 것이다. 해법은 두 가지다. 첫째, 타입 정의를 먼저 공유한다. models.py와 types.ts를 먼저 정의하고, 이후 모든 프롬프트에서 이를 참조하게 만들면 Python-TypeScript 간 타입 불일치라는 가장 흔한 실패 모드를 원천 차단할 수 있다. 둘째, 파일 간 의존 관계를 명시적으로 선언한다. cli.py → job.py → config.py ↔ render-job.ts → ShortsComposition.tsx 같은 의존성 다이어그램을 각 작업 프롬프트에 포함하면 AI가 파일 간 연결을 놓치는 실수를 방지할 수 있다.
한편 Claude Code 활용 관련해서 velog에 공유된 실전 팁도 눈에 띈다. claude.md는 500줄 이하로 유지하고 나머지는 Skill.md로 분리할 것, Extended Thinking은 토큰 비용을 고려해 선택적으로 사용할 것, 작업 관리 도구는 PRD 기반의 Claude Task Master(체계적 프로젝트)와 MVP 지향의 Shrimp Task Master(유연한 프로젝트)를 상황에 맞게 선택할 것—이 원칙들은 모두 하나의 목표로 수렴한다. 컨텍스트를 아끼면서도 에이전트가 방향을 잃지 않게 관리하는 것.
예측 가능한 실패는, 프롬프트에서 미리 막아라
경험 있는 개발자는 안다. 경로 문제, 의존성 버전 충돌, 플랫폼 호환성 이슈는 매 프로젝트에서 동일하게 반복된다. ShortsMaker 사례가 제안하는 '사전 실패 차단(Pre-Emptive Trap Avoidance)' 전략은 단순하지만 강력하다. 이런 예측 가능한 문제들을 프롬프트의 'Must'/'Must not' 제약 조건으로 명시하면, 사후 디버깅 라운드를 한 번 줄일 수 있다. 절대 경로 하드코딩 금지, ^ 버전 핀닝, Remotion 패키지 버전 동기화—이런 규칙들을 AI가 코드를 생성하기 전에 인지하게 만드는 것이다.
시사점: 워크플로우 설계가 곧 AI 활용 역량이다
세 가지 사례가 공통적으로 가리키는 방향은 명확하다. AI 코딩 에이전트를 잘 쓴다는 것은 더 좋은 프롬프트 문장을 아는 게 아니다. 에이전트가 일관성을 유지하고 스스로 검증할 수 있도록 워크플로우 구조 전체를 설계하는 능력이다.
.cursorrules는 에이전트의 행동 규범이고, 아키텍처 문서는 에이전트의 지도이며, 체크포인트 검증은 에이전트의 자기 교정 루프다. 빠른 프로토타이핑과 안정적인 고도화 사이의 간극을 메우는 것도 결국 이 구조적 설계다. AI가 코드를 쓰더라도, 워크플로우의 설계 주도권은 여전히 개발자가 쥐어야 한다.