오늘의 AI 글: Claude Code를 오래 쓰려면 ‘스펙’부터 남겨야 한다

왜 이 글인가

코딩 에이전트를 처음 쓸 때 가장 인상적인 순간은 보통 “함수를 이렇게 빨리 써준다고?”라는 장면이다. 그런데 실제 개발 업무에서 더 자주 부딪히는 문제는 함수 하나가 아니라 기능 하나다. 기능은 요구사항, 예외 케이스, 기존 코드와의 접점, 테스트, 문서, 배포 영향까지 얽혀 있다. Claude Code 같은 에이전트가 짧은 작업에서는 똑똑해 보이다가 세 시간짜리 작업에서 갑자기 산만해지는 이유도 여기에 있다. 원문은 이 문제를 “스펙 없이 코딩하기 때문”이라고 본다.

오늘 고른 글은 Claude Code를 단순 코드 작성 도구가 아니라 기능 빌더로 쓰기 위한 spec-driven development 흐름을 다룬다. 공개적으로 확인 가능한 본문은 Medium 회원 전용 제한 때문에 전체가 아니라 도입부와 메타데이터 중심이었다. 따라서 아래 글은 원문에서 확인한 핵심 주장, 즉 plan mode, interview-to-spec, live task list, durable todos.json mirror라는 네 층의 워크플로를 바탕으로 한국어 독자를 위해 해설·적용 관점으로 재구성한 것이다. 원문 문장을 옮기는 글이 아니라, 코딩 에이전트를 실제 업무에 넣을 때 무엇을 바꿔야 하는지 설명하는 브리핑에 가깝다.

이 주제가 중요한 이유는 2026년의 AI 코딩 도구 경쟁이 “어느 모델이 코드를 더 잘 쓰나”에서 “어느 워크플로가 작업을 끝까지 책임지나”로 이동하고 있기 때문이다. 한 번의 프롬프트로 파일 몇 개를 고치는 데는 이미 여러 도구가 충분히 좋다. 하지만 장기 세션에서는 맥락 손실, 목표 변형, 검증 누락, 중복 수정, 미완성 TODO가 누적된다. 좋은 개발자는 이제 AI에게 일을 시키는 사람을 넘어, AI가 길을 잃지 않도록 작업 구조를 설계하는 사람이 되어야 한다.

특히 Claude Code 사용자라면 이 글이 더 직접적이다. 많은 사용자가 Claude Code에 이미 들어 있는 계획 모드와 작업 목록 기능을 충분히 쓰지 않고, 별도 TODO 파일이나 임시 프롬프트만 덧붙인다. 원문이 던지는 메시지는 간단하지만 날카롭다. 도구가 제공하는 네이티브 작업 관리 계층을 먼저 제대로 써보라는 것이다. 에이전트에게 “알아서 해줘”라고 맡기는 대신, 에이전트가 확인하고 갱신하고 검증할 수 있는 스펙을 만들어야 긴 작업이 버틴다.

핵심 요약

• 원문의 중심 주장은 Claude Code가 짧은 함수 작성기에서 기능 빌더로 넘어가려면 spec-driven development가 필요하다는 것이다. 기능 단위 작업은 “무엇을 만들지”보다 “끝났다는 사실을 어떻게 알지”가 더 중요하다. 스펙은 그 기준을 언어로 고정해주는 장치다.

• 글은 Claude Code 안에 이미 작업 관리에 필요한 기본 계층이 있다고 본다. 공개 메타데이터 기준으로 네 계층은 plan mode, interview-to-spec pattern, live task list, durable todos.json mirror다. 각각은 계획 수립, 요구사항 정제, 실행 중 상태 관리, 세션 이후 복구를 맡는다.

• plan mode의 가치는 바로 코드를 쓰지 않는 데 있다. 에이전트가 파일을 고치기 전에 접근 방식, 영향 범위, 위험한 지점, 검증 방법을 먼저 제안하게 만들면 사용자는 작업의 방향을 초기에 바로잡을 수 있다. 속도는 조금 늦어져도 실패 비용은 크게 줄어든다.

• interview-to-spec은 사용자의 모호한 요청을 에이전트가 질문으로 구체화하는 패턴이다. “로그인 개선해줘” 같은 요청은 구현 범위가 너무 넓다. 에이전트가 대상 사용자, 성공 기준, 예외 상황, UI 변화, 테스트 기준을 묻고 답을 스펙으로 정리해야 실제 구현이 흔들리지 않는다.

• live task list는 긴 작업의 현재 위치를 보여주는 계기판이다. 작업이 길어질수록 사람도 에이전트도 무엇을 끝냈고 무엇이 남았는지 헷갈린다. 실행 중 작업 목록이 살아 있으면 중간에 세션을 멈추거나 방향을 바꿔도 손실이 줄어든다.

• durable todos.json mirror는 작업 상태를 세션 밖에 남기는 장치로 이해할 수 있다. 채팅 기록이나 모델의 임시 맥락에만 의존하면 세션이 끊겼을 때 복구가 어렵다. 파일로 남은 작업 목록은 다음 세션, 다른 에이전트, 사람 리뷰어가 이어받을 수 있는 최소한의 계약이 된다.

• 원문이 말하는 “세 시간째 무너지는 세션”은 모델 지능 부족만의 문제가 아니다. 대부분은 작업의 목표와 상태가 충분히 외부화되지 않은 문제다. 생각이 파일과 체크리스트로 남지 않으면, 에이전트는 앞서 합의한 의도를 점점 느슨하게 기억하게 된다.

• 이 접근은 Claude Code에만 한정되지 않는다. Codex, OpenCode, Cursor, OpenClaw 같은 다른 에이전트 환경에서도 같은 원리가 통한다. 긴 작업일수록 프롬프트보다 스펙, 대화보다 기록, 감탄보다 검증이 중요하다.

• 실무에서 가장 중요한 변화는 “코드 생성 요청”을 “작업 운영 요청”으로 바꾸는 것이다. 에이전트에게 코드를 쓰라고 하기 전에 목표, 비목표, 변경 범위, 완료 조건, 검증 명령, 롤백 기준을 먼저 만들게 해야 한다.

원문의 논지를 단계별로 풀어보기

첫 번째 단계는 문제를 인정하는 것이다. 많은 개발자가 Claude Code를 좋아하면서도 긴 기능 구현에서는 은근히 불안해한다. 처음 한 시간은 훌륭하다. 코드베이스를 읽고, 빠르게 수정하고, 테스트도 돌린다. 그런데 시간이 지나면 작은 TODO가 흩어지고, 처음 정한 요구사항 일부가 빠지고, 검증 없이 “대충 된 것 같은” 상태가 된다. 이때 흔한 반응은 더 자세한 프롬프트를 쓰거나 별도 플러그인을 찾는 것이다. 하지만 원문은 해결책을 더 근본적으로 본다. 작업을 시작하기 전에 스펙을 만들고, 작업 중에는 목록으로 추적하고, 작업 후에는 상태를 남겨야 한다.

두 번째 단계는 plan mode를 작업의 입구로 삼는 것이다. 계획 모드는 “AI가 느려지는 모드”가 아니라 “실수를 싸게 발견하는 모드”다. 실제 파일을 수정하기 전에 에이전트가 어떤 파일을 볼지, 어떤 설계를 택할지, 어떤 테스트가 필요할지 말하게 하면 사용자는 잘못된 가정을 빨리 잡을 수 있다. 예를 들어 결제 로직을 고치려는 작업에서 에이전트가 마이그레이션이나 환불 케이스를 언급하지 않는다면, 구현 전에 바로 경고할 수 있다. 계획은 코드보다 싸고, 잘못된 계획을 고치는 것은 잘못된 PR을 되돌리는 것보다 훨씬 싸다.

세 번째 단계는 interview-to-spec이다. 좋은 에이전트 세션은 사용자의 첫 요청을 그대로 실행하지 않는다. 먼저 질문한다. “관리자와 일반 사용자의 동작이 다른가요?”, “기존 API 계약을 유지해야 하나요?”, “모바일 UI도 포함하나요?”, “성공 기준은 테스트 통과인가요, 특정 사용자 플로우 완료인가요?” 같은 질문이 필요하다. 사용자는 모든 요구사항을 처음부터 완벽하게 말하지 못한다. 에이전트가 질문을 통해 숨어 있는 조건을 끌어내고, 그 답을 스펙 문서나 작업 목록으로 바꾸는 순간부터 긴 작업의 안정성이 올라간다.

네 번째 단계는 live task list로 실행을 관리하는 것이다. 긴 작업에서는 “다음에 뭘 하지?”보다 “지금 어디까지 왔지?”가 더 중요해진다. 작업 목록은 단순 TODO가 아니라 진행 상태의 지도다. 에이전트가 항목을 완료할 때마다 체크하고, 새로 발견한 하위 작업을 추가하고, 막힌 항목을 표시하면 사용자는 중간 개입을 훨씬 쉽게 할 수 있다. 특히 리뷰 중에 “왜 이 파일을 바꿨지?”라는 질문이 생겼을 때 작업 목록은 의사결정의 흔적이 된다.

다섯 번째 단계는 durable mirror다. 세션 안의 맥락은 편하지만 취약하다. 창을 닫거나 컨텍스트가 길어지거나 다른 에이전트로 넘기는 순간, 대화만으로는 작업 상태를 신뢰하기 어렵다. todos.json 같은 파일 기반 미러는 이 취약성을 줄인다. 사람이 읽기 쉬운 마크다운 스펙과 기계가 갱신하기 쉬운 JSON 작업 목록을 함께 두면, 에이전트는 상태를 다시 읽고 이어갈 수 있고 사람은 변경 내역을 리뷰할 수 있다.

여섯 번째 단계는 완료 조건을 명시하는 것이다. “구현 완료”는 너무 느슨하다. 좋은 스펙은 “어떤 테스트가 통과해야 하는지”, “어떤 스크린샷이나 로그를 확인해야 하는지”, “문서 갱신이 필요한지”, “기존 동작이 유지되는지”를 적는다. 에이전트에게 완료 조건이 없으면 가장 그럴듯한 지점에서 멈춘다. 완료 조건이 있으면 검증 가능한 지점에서 멈춘다. 이 차이가 프로토타입과 실무 결과물을 가른다.

마지막 단계는 이 모든 것을 팀의 습관으로 만드는 것이다. 개인이 가끔 긴 프롬프트를 잘 쓰는 것만으로는 부족하다. 저장소 안에 스펙 위치, 작업 목록 형식, 검증 명령, 위험 영역, 승인 규칙이 있어야 한다. 그래야 오늘의 Claude Code 세션, 내일의 Codex 세션, 다음 주의 사람 리뷰어가 같은 작업 맥락을 공유한다. 코딩 에이전트가 많아질수록 작업의 기억을 모델 안이 아니라 저장소 안에 두는 쪽이 더 안전하다.

일반 독자에게 중요한 포인트

• AI가 똑똑해질수록 오히려 “무엇을 시켰는지”를 더 분명히 남겨야 한다. 사람도 회의록 없이 긴 프로젝트를 진행하면 엇갈리듯, AI도 명확한 스펙 없이 긴 작업을 맡으면 중간에 목표가 흐려진다.

• 코딩 에이전트의 실패는 항상 코드 실력 부족에서 오지 않는다. 많은 실패는 요구사항이 모호하거나, 진행 상태가 기록되지 않거나, 완료 기준이 없어서 생긴다. 이는 도구 교체보다 업무 방식 개선으로 더 잘 해결되는 경우가 많다.

• “AI에게 맡긴다”는 말은 방임이 아니다. 좋은 위임은 목표, 권한, 제한, 검증 기준을 함께 주는 것이다. 사람에게 일을 맡길 때도 필요한 요소인데, AI에게는 더 명시적으로 필요하다.

• 스펙은 거창한 문서가 아니라 합의의 기록이다. 짧게는 체크리스트 한 장이어도 충분하다. 중요한 것은 작업이 길어졌을 때 다시 돌아와 기준점으로 삼을 수 있어야 한다는 점이다.

• 앞으로 AI 도구를 잘 쓰는 조직은 프롬프트를 많이 모은 조직이 아니라 작업 맥락을 잘 남기는 조직일 가능성이 크다. 코드, 테스트, 문서, 작업 목록이 함께 움직이면 에이전트의 생산성이 일회성 데모를 넘어선다.

적용 아이디어

• 큰 작업을 시작할 때 에이전트에게 바로 구현하지 말고 먼저 스펙 초안을 만들라고 지시한다. 초안에는 목표, 비목표, 사용자 영향, 변경 파일 후보, 위험 요소, 검증 방법을 포함한다.

• 사용자의 요청이 모호하면 에이전트가 최소 5개의 질문을 하도록 습관화한다. 질문은 기능 범위, 기존 호환성, 에러 처리, 테스트 기준, 배포 영향처럼 실제 실패로 이어지는 영역에 집중한다.

• 저장소에 docs/specs/ 또는 .agent/specs/ 같은 위치를 정하고 긴 작업의 스펙을 남긴다. 임시 채팅 안에만 요구사항을 두지 않는다. PR 설명에도 해당 스펙 링크를 걸면 리뷰가 쉬워진다.

• 작업 목록은 사람이 읽는 마크다운과 에이전트가 갱신하기 쉬운 JSON 중 하나만 고집하지 말고, 필요하면 둘 다 둔다. 예를 들어 feature-auth-refresh.md에는 배경과 결정사항을, todos.json에는 상태와 체크 항목을 남긴다.

• 완료 조건을 “테스트 통과” 하나로 끝내지 않는다. 테스트 명령, 수동 확인 경로, 로그 확인, 문서 갱신, 롤백 가능성까지 적는다. 특히 인증, 결제, 데이터 마이그레이션 같은 영역은 별도 승인 조건을 둔다.

• 에이전트가 작업 목록을 갱신할 때마다 실제 변경과 맞는지 확인한다. 체크리스트가 현실과 어긋나면 오히려 위험하다. 완료 표시가 된 항목에는 테스트 결과나 확인 근거를 짧게 붙이게 한다.

• 긴 세션은 중간 검증 지점으로 쪼갠다. 계획 승인, 첫 번째 작은 변경, 테스트 실행, 전체 적용, 최종 리뷰 순서로 진행하면 세 시간 뒤에 한꺼번에 실패를 발견하는 일을 줄일 수 있다.

• 도구별 기능에 매달리기보다 원칙을 이식한다. Claude Code에서는 plan mode와 task list를 쓰고, Codex에서는 작업 지시와 PR 검증 기준을 더 명확히 하며, OpenCode나 OpenClaw에서는 저장소 안 지침 파일과 체크리스트를 적극 활용한다.

읽기 우선순위

Claude Code를 이미 쓰고 있고, 특히 “처음엔 잘하다가 긴 작업에서 흐트러진다”는 느낌을 받은 개발자라면 원문을 우선순위 높게 읽을 만하다. 다만 공개 접근만으로는 전체 본문을 확인하기 어려웠으므로, Medium 회원 접근이 가능하다면 원문에서 네이티브 작업 목록과 todos.json 미러를 실제로 어떻게 연결하는지 확인하는 것이 좋다.

시간이 부족하다면 핵심만 가져가도 된다. 큰 작업은 바로 구현하지 말고 계획을 세운다. 모호한 요청은 질문으로 스펙화한다. 실행 중에는 살아 있는 작업 목록을 유지한다. 세션 밖에도 상태를 남긴다. 이 네 가지를 지키면 Claude Code뿐 아니라 거의 모든 코딩 에이전트의 장기 작업 안정성이 올라간다. 오늘 읽을 이유는 분명하다. AI 코딩의 다음 생산성은 더 긴 프롬프트가 아니라 더 오래 버티는 작업 구조에서 나온다.