AI 코딩에 대해 알던 모든 것이 틀렸습니다

Beemad, Speckit 등 기존 AI 코딩 프레임워크들이 존재하지만, 많은 경우 약속한 성능을 제대로 구현하지 못하는 이유를 설명합니다. 이는 프레임워크 자체의 문제가 아니라 사용자의 특정 사용 사례에 맞지 않기 때문입니다. 앱을 만들 때 미리 만들어진 워크플로우에 의존하기보다 자신만의 워크플로우를 직접 구축하는 것이 중요합니다. 워크플로우는 특정 사용 사례를 중심으로 구축되어야 하며, 프로젝트와 일치할 때만 제대로 작동한다는 핵심 메시지를 전달합니다.

AI 도구의 컨텍스트 윈도우가 무엇인지, 왜 중요한지를 설명합니다. 컨텍스트 윈도우는 모델이 한 번에 기억할 수 있는 정보의 양으로, 이를 관리하는 것이 프레임워크의 기본 역할입니다. Anthropic 모델은 20만 토큰, Gemini는 100만 토큰의 윈도우를 가지지만, 실제로는 시스템 프롬프트와 사용자 메시지뿐만 아니라 과거 메시지, 메모리 파일, 도구, MCP 호출 등 많은 요소들이 포함됩니다. 겉보기에 큰 숫자처럼 보이지만 실제로는 제한적이므로, 이 제한된 작업 공간을 최대한 활용하는 방법을 배워야 워크플로우 구축 시 모델이 정확히 원하는 대로 작동하게 할 수 있습니다.

모든 워크플로우 설계의 핵심인 점진적 공개 원칙을 소개합니다. 이는 LLM에게 중요한 것만 보여주고, 지금 실제로 필요한 것에 모델의 주의를 집중시키는 것을 의미합니다. Sonnet 4.5 같은 고급 모델들은 내장 컨텍스트 편집 기능이 있지만, 모호한 지시를 내리면 여전히 불필요한 것들을 로드하여 윈도우를 오염시킵니다. 예를 들어 백엔드 오류를 수정할 때 한 번에 모든 것을 고치라고 하기보다 엔드포인트를 하나씩 확인하라고 요청하는 것이 더 효과적입니다. Claude의 스킬 기능은 점진적 공개의 구체화로, 모든 것을 컨텍스트에 로드하지 않고도 각 스킬을 언제 사용해야 하는지 알 수 있게 합니다. MCP는 외부 데이터가 필요할 때만 사용하고, 그 외에는 스킬을 사용해야 한다는 중요한 지침도 제공합니다.

지금 당장 필요하지 않은 정보는 컨텍스트 윈도우에 속해서는 안 된다는 두 번째 핵심 원칙을 설명합니다. 이를 위해 도구들은 구조화된 노트 작성을 사용하며, AI 도구에 결정 사항, 문제, 기술 부채를 문서화하는 외부 파일을 제공함으로써 이를 활용할 수 있습니다. 이 접근 방식은 복잡한 것을 구축할 때 잃어버릴 수 있는 중요한 컨텍스트를 에이전트가 유지하도록 도와줍니다. 컨텍스트가 재설정될 때 압축 요약에만 의존하는 대신, 에이전트는 노트를 사용하여 이미 완료된 작업과 해야 할 작업에 대한 컨텍스트를 얻을 수 있습니다. agent.md와 claude.md 같은 표준 컨텍스트 파일을 활용하여 외부 파일의 구조와 작성 방법을 에이전트에게 안내할 수 있습니다.

에이전트가 장시간 작업 중 무작위로 멈추는 현상이 주로 컨텍스트가 한계의 70%를 초과했을 때 발생한다는 문제를 다룹니다. 주의 예산의 개념을 소개하며, 컨텍스트 윈도우는 모델이 출력 생성 시 주의를 기울이는 대상이라고 설명합니다. 70%를 넘어가면 모델은 더 집중해야 하고 환각 가능성이 높아지며, AI 에이전트는 도구를 효과적으로 사용하지 못하고 종종 무시합니다. 이를 해결하기 위해 90%까지 채워지게 내버려두고 자동 압축에 의존하기보다, 컨텍스트 윈도우를 주시하고 직접 압축해야 합니다. Claude의 내장 되감기 기능을 활용하여 불필요한 부분을 삭제하고, 새 작업에는 컨텍스트 윈도우를 지우거나 새로 시작하는 것이 권장됩니다.

점진적 공개 원칙에서 비롯된 개념으로, 하위 에이전트가 메인 컨텍스트 윈도우를 오염시키지 않고 백그라운드에서 작업을 실행하는 방법을 설명합니다. 하위 에이전트는 자체 격리된 컨텍스트 윈도우에서 작업하고 메인 에이전트에게 출력만 보고합니다. 이는 서로 격리된 작업을 수행할 때 특히 유용한데, 메인 컨텍스트 윈도우가 하위 에이전트의 도구 호출 및 검색으로 비대해지는 것을 방지하고 정보를 전용 작업 영역에 남겨둡니다. 백그라운드에서 실행되므로 메인 에이전트와 계속 상호작용하면서 주의가 필요한 작업을 수행할 수 있으며, 무언가를 조사할 때 하위 에이전트를 사용하면 도구 호출과 검색이 격리되고 답변만 반환받을 수 있습니다.

노트 작성 시 어떤 작업에 어떤 파일 형식을 사용해야 하는지 설명하며, 각 형식이 토큰 수와 워크플로우 효율성에 미치는 영향을 다룹니다. YAML이 가장 토큰 효율적이므로 데이터베이스 스키마, 보안 설정, API 세부 정보에 사용되며, 들여쓰기가 모델의 정보 구조화를 돕습니다. Markdown은 claude.md 같은 문서화에 적합하며, 제목 수준이 모델의 섹션 간 탐색을 용이하게 합니다. XML은 특별히 Claude 모델에 최적화되어 있으며, Anthropic은 자사 모델이 이러한 태그를 컨테이너 및 구분자로 인식하도록 미세 조정했다고 밝혔습니다. 제약 조건, 요약, 시각적 세부 사항 같은 구별되는 섹션이 있을 때 유용하며, 다른 모델들은 일반적으로 XML보다 Markdown과 YAML을 선호합니다. JSON은 추가 괄호와 따옴표로 인해 토큰 효율성이 가장 낮아 작업 상태 같은 작은 것에만 사용을 권장합니다.

컨텍스트 워크플로우에서 Git을 활용하는 방법을 설명합니다. Git 커밋 히스토리를 전체 프로젝트 또는 단일 작업에 걸친 진행 상황에 대한 모델의 알림으로 사용하는 트렌드가 있습니다. 진행 상황 저장 용도가 아니더라도, 일반적으로 Git이 초기화된 저장소에서 컨텍스트 엔지니어링 워크플로우를 사용해야 합니다. 컨텍스트 엔지니어링 워크플로우는 모델이 모든 것을 한 번에 처리하는 것이 아니라 계획된 단계를 하나씩 실행하도록 하는 것을 의미합니다. 어느 단계에서든 문제가 발생하면 Git을 통해 어느 버전으로 되돌릴지 제어하고 어떤 변경 사항이 문제를 일으키는지 평가할 수 있습니다. Git worktree를 사용하여 병렬 처리를 구현하고, 하위 에이전트들이 전용 worktree에서 병렬 작업을 수행하도록 할 수 있습니다.

워크플로우를 만들 때 일반적인 절차에 대한 지시사항을 반복하게 되는 경우를 해결하기 위한 커스텀 명령어 활용법을 설명합니다. Git 커밋이나 문서 업데이트 요청 방식이 좋은 예시이며, 거의 모든 AI 도구에는 가장 자주 반복되는 프롬프트를 재사용할 수 있는 방법이 있습니다. 프로젝트에서 커스텀 명령어를 자주 사용하는데, 이는 Claude에게 재사용 가능한 가이드를 제공하기 때문입니다. catchup 명령어는 컨텍스트 윈도우 밖에서 메모리를 구조화하는 방법에 대한 지시사항을 포함하여 Claude가 모든 파일을 읽는 대신 프로젝트를 따라잡을 수 있게 합니다. commit 명령어는 커밋 메시지 작성 방법과 사전 검사에 대한 특정 구조를 따르도록 하여, 모든 것을 표준화된 상태로 유지하고 선호하는 방식으로 작업하도록 반복 지시할 필요를 없앱니다.

외부 데이터가 필요할 때 MCP를 사용해야 하는 시점과 방법을 설명합니다. Jira는 가장 널리 사용되는 팀 관리 소프트웨어로, 티켓에서 정보를 가져오려면 Jira MCP를 사용하여 티켓에 직접 접근하고 변경 사항 구현을 시작할 수 있습니다. 마찬가지로 Figma MCP를 사용하여 Claude 코드에 앱의 스타일 가이드를 제공하고, Claude는 이를 사용하여 디자인을 구성합니다. 모델의 기본 기능이 부족한 작업의 경우, MCP는 외부 소스와 효율적으로 상호작용하는 데 필수적입니다. 이러한 MCP들을 명령어에 직접 포함시켜 전체 워크플로우의 일부로 만들 수 있으며, 이를 통해 외부 데이터 통합을 자동화하고 효율성을 높일 수 있습니다.