Loading summary...
수개월 동안 클로드 코드를 주력 개발 도구로 사용하면서 정착한 워크플로우는 대부분의 사람들이 AI 코딩 도구를 사용하는 방식과 차이가 있다.
프롬프트 작성, 플랫 모드 사용, 에러 수정 반복, 랄프루프, MCP, 스킬, 팀 에이전트 등 다양한 시도들이 이루어지지만, 작업이 복잡해지는 순간 결과물이 무너지는 경우가 많다.
작성된 계획을 직접 검토하고 승인하기 전까지 클로드에게 코드를 쓰게 하지 않는 것이 핵심이다.
쓸데없는 삽질이 사라지고, 아키텍처 결정에 주도권이 유지되며, 토큰을 적게 쓰면서 결과물의 품질이 향상된다.
코드 리서치, 계획, 주석 달기, 최소 한 번 이상 반복, 구현, 피드백 반복. 간단한 작업의 경우 일부 단계를 건너뛸 수 있다.
모든 의미 있는 작업은 코드 베이스를 깊이 읽는 것부터 시작한다. 클로드에게 관련 부분을 철저하게 이해하도록 지시하고, 발견한 내용을 마크다운 파일(리서치 MD)에 작성하게 한다. 채팅창 안에서 코드 요약으로 끝내면 안 된다.
"이 폴더를 깊이 읽고 어떻게 동작하는지 깊이 이해하고 모든 세부 사항을 파악해라. 끝나면 리서치의 상세 보고서를 작성해라. 알림 시스템을 매우 상세히 연구하고 알림이 어떻게 작동하는지 모든 것을 담은 리서치 MD를 작성해라."
깊이, 매우 상세히, 세부 사항 등의 단어를 사용하여 클로드가 대충 훑어보지 않고 깊이 있는 분석을 하도록 유도한다.
문법 에러나 로직 버그가 아니라, 주변 시스템을 슬금슬금 망가뜨리는 구현이다. (예: 기존 레이어를 무시하는 함수, ORM 관리를 고려하지 않은 마이그레이션, 중복된 API 엔드포인트 등) 리서치 단계는 이러한 문제를 예방하는 데 도움이 된다.
리서치 검토 후, 별도의 마크다운 파일에 상세 구현 계획을 작성한다.
"새 기능 ETF 리밸런싱을 구현하는 상세 플랜 MD를 작성해라. 코드 스니펫도 포함. 목록에서 오프셋 페이징 대신 인풋 기반 페이징을 지원해야 함. 이를 위한 상세 플랜 MD를 작성해 줘. 변경 사항을 제한하기 전에 소스 파일을 읽고 실제 코드베이스를 기반으로 계획을 작성해."
접근 방식에 대한 상세 설명, 실제 변경 사항을 보여주는 코드 스니펫, 수정될 파일 경로, 고려 사항, 트레이드 오프.
내장 플랫 모드는 별로이므로 자체 MD 파일을 사용하는 것이 좋다. 에디터에서 직접 편집, 인라인 메모 추가, 프로젝트 내 산출물로 보관 가능. 채팅창에 흘러가는 플랜과는 차원이 다르다.
잘못된 가정 수정, 접근 방식 거부, 제약 조건 추가, 클로드가 알 수 없는 도메인 지식 제공. 메모 길이는 다양하며, 코드 스니펫을 포함하기도 한다.
"문서에 몇 가지 메모를 추가했어. 모든 메모를 반영하고 문서를 업데이트해. 아직 구현하지 마." 라고 명시적으로 지시해야 한다. 이 사이클은 1번에서 수번 정도 반복될 수 있다.
명시적으로 "아직 구현하지 마"라고 써 줘야 클로드가 혼자 판단해서 코드를 짜기 시작하는 것을 막을 수 있다.
계획이 완전히 준비되면 구현 명령을 내린다. 표준 프롬프트를 재사용한다.
"전부 구현해라. 작업이나 단계를 완료하면 계획 문서에서 완료로 표시해라. 모든 작업과 단계가 완료될 때까지 멈추지 마라. 너운 타입을 쓰지 마라. 지속적으로 타입 체크를 실행해서 새로운 문제를 만들지 마라."
모든 결정이 이미 내려지고 검증된 상태이므로 구현은 기계적으로 이루어진다. 창의적인 작업은 주석 달기 사이클에서 이미 완료되었다.
클로드가 계획을 실행하는 동안 설계자/아키텍트에서 감독자로 역할이 바뀐다.
프롬프트가 극적으로 짧아진다. (예: "리밸런스 이벤트 함수를 구현 안 했잖아.", "설정 페이지를 메인 앱에 만들었는데 어드민 앱에 있어야 해. 옮겨.")
브라우저에서 테스트하면서 빠른 수정을 지시하는 단계이다. 디자인적 문제의 경우 스크린샷을 첨부하는 것이 효율적이다.
잘못된 방향으로 가고 있다면 절대 그 위에서 패치하려고 하지 말고, 깃을 통째로 되돌리고 범위를 재설정한다.
깃 리셋 또는 리버트하고 범위를 좁히는 것이 점진적으로 고쳐나가는 것보다 더 좋은 결과를 만든다.
클로드에게 실행은 맡기지만, 무엇을 만들지에 대한 결정권은 절대 넘기지 않는다. 적극적인 방향 조정은 대부분 플랜 MD 문서 위에서 이루어진다.
리서치, 기획, 구현을 별도 세션으로 나누지 않고 하나의 긴 세션 안에서 쭉 이어간다.
컨텍스트 윈도우가 50% 넘어가면 성능이 떨어진다는 이야기가 있지만, 전부 구현하라고 말할 시점에 클로드는 이미 리서치, 계획, 주석 반영을 통해 이해를 쌓아온 상태이므로 큰 문제가 되지 않는다.
컨텍스트 윈도우가 꽉 차면 클로드의 오토 컨팩션이 충분한 맥락을 알아서 유지해 준다.
계획 문서는 영구적인 파일이므로 압축되든, 변환되든 원본 그대로 살아남는다.
깊이 읽고, 계획을 작성하고, 계획이 맞을 때까지 주석을 달고, 클로드가 멈추지 않고 전부 실행하게 한다. 타입 체크는 계속 돌린다.
마법 같은 프롬프트, 정교한 시스템 인스트럭션, 영리한 해킹은 필요 없다. 생각하는 것과 타이핑하는 것을 분리하는 규율 있는 파이프라인이 중요하다.
클로드한테 코드를 잘 쓰게 만드는 게 아니라, 코드를 쓰기 전에 뭘 써야 하는지를 확실하게 만드는 것이 전부다.
플랜 MD 파일에 직접 메모를 달고, 클로드가 작성한 구현 계획서 안에서 특정 위치에 인라인으로 메모를 추가한다. 매번 클로드에게 메모 추가했으니 반영하고 업데이트해, 아직 구현하지 마라고 보낸다. 이를 만족할 때까지 반복한다.
채팅창에서 이것저것 설명하는 게 아니라, 문서의 정확한 위치를 가리키면서 수정 사항을 직접 적는 것이 쉐어드 뮤터블 스테이트 패턴이며, 에이전트 코딩 워크플로우에서 가장 실용적인 인간 주도 루핑 방법론이다.