AI 페어 프로그래밍은 자동 항법 장치가 아니다: HandyFEM의 스캐폴딩(Scaffolding)과 AI가 버린 것 잡아내기

에이전트가 코드를 작성합니다. 하지만 당신은 여전히 엔지니어입니다.

저는 Claude Code를 페어 프로그래머로 삼아 HandyFEM을 구축하고 있습니다. 속도가 빠릅니다 — 때로는 놀라울 정도입니다. 하지만 제가 협업하는 방식은 의도적입니다. 에이전트가 생성하는 모든 것을 유능한 주니어 개발자가 보낸 풀 리퀘스트(Pull Request)를 대하는 것과 똑같이 취급합니다. 읽고, 의문을 제기하며, 무엇을 남길지 결정합니다.

이 포스트는 왜 그러한 습관이 중요한지에 대한 구체적인 사례입니다.

작업: 프로젝트 스캐폴딩 (Scaffolding)

기능을 작성하기 전에, 프로젝트의 스캐폴딩(Scaffolding)을 수행합니다 — 즉, 폴더 구조, 설정 파일, 실행 가능한 기본 페이지와 같은 뼈대를 생성하는 것입니다. 저는 에이전트에게 HandyFEM의 기반을 설정하도록 했습니다:

• TypeScript와 Tailwind를 사용하는 Next.js
• shadcn/ui — 컴포넌트 코드가 저장소(Repo)에 존재하므로 직접 소유하게 됩니다.
• 테마에 연결된 디자인 토큰(Design tokens) — 제 사양서에 명시된 정확한 색상 팔레트 적용

제 프로젝트 폴더에는 이미 docs, Git, 그리고 실제 비밀값이 담긴 .env.local이 있었기 때문에, 에이전트는 영리하게 행동했습니다. 기존 파일을 덮어쓰지 않고 임시 폴더에 앱을 생성한 뒤 신중하게 통합했습니다.

놓칠 뻔한 부분

통합 과정에서 에이전트는 — 거의 지나가는 말로 — Next.js 생성기가 자체적인 CLAUDE.md 파일을 생성했으며, 제 파일을 덮어쓰지 않기 위해 그것을 **버렸다(discarded)**고 언급했습니다.

표면적으로는: 올바른 동작입니다. 하지만 저는 그냥 지나치고 싶지 않은 의문이 생겼습니다. 그 버려진 파일에 유용한 내용이 들어있지는 않았을까?

그래서 물어보았습니다. 우리는 다시 돌아가 확인했습니다. 생성된 CLAUDE.md는 두 번째 파일인 AGENTS.md를 가리키고 있었고, 그 파일에는 정말 가치 있는 내용이 담겨 있었습니다:

# 이것은 당신이 알고 있는 Next.js가 아닙니다

이 버전에는 파괴적 변경 사항(Breaking changes)이 있습니다 — API, 컨벤션(Conventions), 파일 구조가...

실제 상황이었습니다. 제가 사용하는 프레임워크 버전은 대부분의 AI 모델이 학습된 시점보다 최신입니다. 이 노트를 놓쳤다면 에이전트는 나중에 구식 패턴을 사용하여 — 자신 있게, 그리고 틀리게 — 코드를 작성했을지도 모릅니다.

우리는 그 내용을 프로젝트 지침(Instructions)으로 구조화하여 구출해냈습니다. 작은 메모 하나일 뿐이지만, 이는 향후 작성될 모든 프레임워크 코드의 품질을 바꿉니다.

이것이 중요한 이유

에이전트가 잘못한 것은 없습니다. 내 파일을 보호하기 위해 파일을 폐기한 것은 합리적인 결정이었습니다. 하지만 그 부작용, 즉 중요한 컨텍스트 (Context)를 놓친 것은 훨씬 더 큰 작업 중에 단 한 줄의 부연 설명 속에 파묻혀 있어 놓치기 쉬웠습니다.

이것이 바로 내재화해야 할 패턴입니다. AI 에이전트는 빠르고 그럴듯한 결정을 대량으로 내립니다. 대부분은 훌륭합니다. 하지만 "그럴듯함"이 곧 "검토됨"을 의미하지는 않습니다. 기술은 프롬프팅 (Prompting)이 아닙니다. 리뷰어처럼 출력물을 읽는 것입니다. 무엇을 변경했는지, 무엇을 삭제했는지, 그리고 그 각각이 내가 실제로 원하는 것인지 확인하는 능력입니다.

내가 리뷰를 하는 이유는 도구가 나쁘기 때문이 아닙니다. 도구가 너무 훌륭해서, 그렇지 않으면 주의를 기울이지 않게 될 정도이기 때문입니다. 그것이 바로 함정입니다.

워크플로우에 대한 솔직한 회고

잘 작동하고 있는 점:

• 기능보다 보안 우선. 스캐폴딩 (Scaffolding)을 시작하기 전에 프리 커밋 훅 (Pre-commit hook), .gitignore, 환경 변수 등을 모두 설정했습니다. 신뢰가 전제 조건인 제품에게 이러한 순서는 타협할 수 없는 부분입니다.
• 신뢰할 수 있는 근거로서의 상세 사양 (Specs). 에이전트는 무언가를 발명하도록 유도받는 대신, 실제로 구현할 화면, 컴포넌트 (Components), 컬러 팔레트 (Color palette)를 가지고 있었습니다.
• 프로젝트 컨벤션 (Conventions)이 담긴 CLAUDE.md. 모바일 퍼스트 (Mobile-first), 접근성 최소 기준, 비밀 정보 하드코딩 금지 등. 에이전트는 일반적인 기준 대신 나의 표준을 기본값으로 사용합니다.

개선하고 싶은 점:

• 경로를 결정하기 전에 수동 vs 자동을 결정할 것. 초기에는 에이전트에게 일회성 설정 작업을 스크립트로 작성하게 했습니다. 이는 긴 디버깅 (Debugging) 세션으로 이어졌습니다. 직접 손으로 하는 것이 더 빨랐을 것입니다. 자동화는 무언가를 반복할 때 가치가 있습니다. 진정한 일회성 작업의 경우, 수동 작업이 종종 더 현명합니다.
• 새 스레드를 열기 전에 목록을 점검할 것. 열려 있는 질문이라고 생각했던 일부 질문들은 이미 나의 사양 (Specs)에 답이 있었습니다. 5분간의 검토가 이미 결정된 사항을 다시 논쟁하는 시간을 아껴줍니다.

메타 레슨 (Meta-lesson): AI 에이전트와 함께할 때 병목 현상 (Bottleneck)은 이동합니다. 더 이상 코드를 작성하는 것이 아니라, 잘 결정하고 주의 깊게 리뷰하는 것이 병목이 됩니다. 타이핑의 가치는 저렴해졌습니다. 판단력의 가치는 낮아진 것이 아니라 더욱 높아졌습니다.

요약 (Takeaway)

AI 에이전트(AI agent)는 진정한 승수 효과(force multiplier)를 제공하지만, 이는 오직 운전석을 지키고 있는 사람에게만 해당됩니다. 에이전트는 당신보다 빠르게 움직이고, 대부분 괜찮은 결정을 내리겠지만, 때로는 당신이 대충 훑어보고 지나칠 법한 문장에서 중요한 무언가를 놓칠 수도 있습니다.

그러니 대충 훑어보지 마세요. 차이점(diff)을 읽으세요. "무엇을 삭제했나요, 그리고 왜 그랬나요?"라고 물으세요.

에이전트가 코드를 작성합니다. 당신은 여전히 엔지니어입니다.

#HandyFEMApp #BuildingInPublic #AI #ClaudeCode #WebDev