코딩 에이전트 덕분에 명세서(Specs)를 진지하게 다루게 된 이유

모든 것이 매우 빠르게 변했습니다.

며칠 만에 DataCamp에서의 제 업무는 대부분 수동으로 코딩하고 디버깅하던 방식에서 Claude Code를 통해 많은 부분을 처리하는 방식으로 바뀌었습니다. 구현이 수동적이고 거의 예술적이었던 그 긴 세션들이 완전히 사라진 것은 아니지만, 그 성격이 변했습니다.

그 변화는 점진적이었다가, 어느 순간 갑자기 명확해졌습니다.

Leo(레오)의 등장과 함께 제 개인적인 삶에서도 많은 것들이 변했습니다. 이것이 무엇에 관한 내용인지 모르신다면, 이 시리즈의 첫 번째 포스트를 확인해 보세요. 갑작스러운 컨텍스트 스위칭 (Context Switching)은 제가 강제로 개발해야만 했던 기술이 되었습니다. 집에 아기가 있으면 방해받지 않는 작업 세션이란 존재하지 않습니다. 중간에 항상 기저귀 갈기, 젖병 물리기, 목욕, 또는 놀아주기 같은 일들이 끼어듭니다.

그리고 물론, 에너지 상태도 항상 일정하지 않습니다.

다행히 Leo는 잠을 꽤 잘 자지만, 낮 시간과 마찬가지로 실제로 사용할 수 있는 시간은 파편화되어 있습니다. 이제는 문제에 몰입하여 이해하고, 구현하고, 테스트하고, 마무리하기 위해 몇 시간씩 연속된 시간을 가질 수 있다고 기대할 수 없습니다. 이제는 끊임없는 방해 속에서도 살아남을 수 있는 작업 방식이 필요합니다.

바로 이 지점에서 명세서 (Specs)가 단순한 형식처럼 느껴지는 것을 넘어 생존 도구가 되었습니다.

제 정확한 설정(Setup)에 관심이 없으시다면, 유용한 부분은 이것입니다: 작업이 이미 테스트 가능한 무언가로 변환되어 있을 때 에이전트 (Agents)는 훨씬 더 나은 성능을 발휘합니다. 완벽한 문서일 필요는 없습니다. 기업의 요구사항 프로세스일 필요도 없습니다. 그저 에이전트가 제품, 제약 조건, 그리고 결승선을 동시에 추측할 필요가 없을 정도의 형태만 갖추면 됩니다.

순간을 활용하기

이것이 바로 에이전트 덕분에 제가 사이드 프로젝트를 어느 정도 연속성을 가지고 계속 진행할 수 있게 된 부분입니다. 시간이 흐르면서, 프롬프트 (Prompts)와 개인적인 습관의 모음으로 시작했던 것이 Harness로 발전했습니다. Harness는 기술, 문서, 훅 (Hooks), 서브 에이전트 (Subagents), 그리고 작은 가드레일 (Guardrails)로 패키징된 저만의 개발 워크플로우 (Workflow)입니다.

이것은 제품으로 시작된 것이 아닙니다. 단순히 컴퓨터 앞에 앉아 코드를 작성하는 것만으로는 더 이상 충분하지 않았기 때문에 시작되었습니다.

실제로 Harness는 Claude Code 기술들의 집합체입니다. 즉, 어떤 파일을 읽어야 하는지, 어떤 질문을 던져야 하는지, 그리고 어떤 문서를 생성해야 하는지를 알고 있는 슬래시 명령어 (slash commands)들의 모음입니다. 각 명령어는 사용자가 자리에 앉아 있지 않아도 실행될 수 있습니다. 사용자는 나중에 결과물로 돌아와 이를 검토하고 다음 단계를 지시하면 됩니다. 구조가 어떻게 되어 있는지 확인하고 싶다면 repo를 공개해 두었습니다.

모든 것은 아이디어에서 시작됩니다. 이는 대개 저의 전문적인 필요(개발자로서 그리워하는 도구 등)나 개인적인 필요(일상생활에 도움이 될 만한 도구 등) 중 하나에서 비롯됩니다.

처음에는 아이디어를 정립하기 위해 Claude Code의 도움을 받으며 이 단계를 수동으로 진행했습니다. 이제는 /ideate 명령어로 흐름이 시작됩니다. 이 명령어는 제가 아이디어에 너무 깊이 빠지기 전에 경쟁사, 고통 지점 (pain signals), 그리고 실행 가능성 (viability)을 조사합니다. 만약 여전히 타당성이 있다면, /product-plan이 비전을 타겟 고객, 포지셔닝, 로드맵, UX 방향성 및 리스크로 전환합니다.

아이디어는 간단합니다. 막연한 직관에서 바로 구현 (implementation) 단계로 뛰어드는 대신, Harness는 제가 무엇을 만들고 싶은지, 누구를 위한 것인지, 왜 타당한지, 그리고 무엇을 제외해야 하는지를 설명하도록 강제합니다.

결과물은 .harness/product/ 디렉토리에 저장됩니다: idea.md, product.md, roadmap.md, competitors.md, 그리고 도메인 어휘 (domain vocabulary)가 담긴 CONTEXT.md가 있습니다. 마지막 파일은 작아 보일 수 있지만 매우 중요합니다. 제품 내에 특정 개념에 대한 이름이 있다면, 저는 에이전트가 명세서 (specs), 코드, 그리고 문서에서 그 이름을 사용하기를 원합니다.

다음 단계는 /dev-plan입니다. 제품 명세서 (product specs)는 아키텍처 (architecture), 스택 결정 (stack decisions), 구현 계획 (implementation plan), ADR (Architecture Decision Records), 그리고 필수 기능 (must-have feature)당 하나의 기능 명세서 (feature spec)로 변환됩니다. 각 기능 파일에는 목표, 범위 (scope), 기술적 접근 방식 (technical approach), 엣지 케이스 (edge cases), 그리고 수락 기준 (acceptance criteria)이 포함됩니다.

따라서 코드 한 줄을 쓰기도 전에 프로젝트는 이미 명확한 형태를 갖추게 됩니다. 우리가 무엇을 만드는지, 누구를 위한 것인지, 어떤 결정이 작업을 제약하는지, 그리고 기능이 완료되었음을 어떻게 알 수 있는지에 대한 내용 말입니다. 항상 완벽한 것은 아니지만, 에이전트가 컨텍스트 (context)를 가지고 시작하기에는 충분히 훌륭합니다.

그 차이는 작지만 중요합니다. 매우 단순화된 예시를 들어보겠습니다:

내보내기 흐름(export flow)을 구축하고 잘 작동하는지 확인하세요.

반면, 에이전트에게 기회를 주는 명세서(spec)는 다음과 같은 형태입니다:

SP-404 팩을 위한 내보내기 흐름(export flow)을 구축하세요.

제약 사항(Constraints):
...

이것 역시 엄청나게 방대한 문서는 아닙니다. 하지만 이제는 검증할 무언가, 거절할 무언가, 그리고 검토할 무언가가 존재하게 됩니다.

이 과정은 보통 저에게 한두 번의 낮잠 시간을 요구합니다. 저는 구현 중간에 전략을 바꾸는 것보다, 긴 대화를 통해 개념을 제대로 정립하는 쪽을 택하겠습니다. 시간이 이토록 파편화되어 있을 때, 즉흥적으로 대처하는 것은 비용이 많이 듭니다.

이러한 문서들을 갖추고 나면, 다음 단계인 구현(implementation)이 시작됩니다.

위임하는 법 배우기

구현을 위해 저는 여러 가지 전략과 기술을 시도해 보았습니다. 그중 살아남아 현재 Harness에 내장된 것들은 다음과 같습니다.

/implement는 명세서(specs)를 읽고, 어떤 기능이 AFK(자리를 비운 사이)에 처리 가능한지, 어떤 기능에 인간의 승인이 필요한지를 분류하며, 현재 단계를 수직적 슬라이스(vertical slices)로 구현합니다. 이 부분이 중요한데, 하나의 에이전트에게 "프론트엔드"를 맡기고 다른 에이전트에게 "백엔드"를 맡기는 방식이 아니기 때문입니다. 각 에이전트는 사용자 접점(entry point)부터 필요한 데이터 계층(data layer)에 이르기까지 하나의 기능을 엔드 투 엔드(end to end)로 구현합니다.

그 뒤에는 /qa가 이어지며, 해당 기능들을 수락 기준(acceptance criteria)에 따라 테스트합니다. 단순히 테스트 스위트(test suite)를 실행하는 데 그치지 않습니다. API의 경우 curl을 사용할 수 있고, CLI의 경우 피스처(fixtures)와 함께 명령어를 실행할 수 있으며, 웹 앱의 경우 Playwright를 사용할 수 있습니다. 핵심은 가시적인 동작(visible behavior)을 검증하는 것입니다.

연속성을 유지하는 기술들도 있습니다. /update-docs는 문서를 코드의 실제 상태와 동기화하고, /next-step은 저장소(repo)를 조사하여 다음에 무엇을 해야 할지 권장하며, /handoff는 다음 세션이 아무 정보 없이 시작되지 않도록 요약본을 남기고, /task는 출시된 제품의 작은 변경 사항들을 처리합니다.

워크트리(Worktrees)는 여전히 병렬화를 위한 핵심 요소입니다. 여러 에이전트가 서로 방해하지 않고 동일한 머신 내의 동일한 저장소에서 서로 다른 브랜치(branch)를 통해 작업할 수 있습니다.

마법 같습니다.

따라서 도구들이 준비되었다면, 이제 남은 것은 에이전트(agents)를 실전에 투입하는 것뿐입니다. 저는 두 개의 프로젝트와 두 개의 로드맵 항목(roadmap items)을 선택하고, 각각을 위한 터미널 세션과 워크트리(worktree)를 연 다음, Leo가 깨어나기 전에 실행을 시작합니다.

여기서 중요한 점은 많은 도구를 갖는 것이 아닙니다. 중요한 점은 각 도구가 서둘러 작성된 느슨한 프롬프트(prompt)보다 더 명확한 무언가를 전달받는 것입니다. 도구는 컨텍스트(context), 목표(goals), 제약 조건(constraints), 수락 기준(acceptance criteria), 그리고 언제 멈춰야 하는지에 대한 합리적인 아이디어를 전달받습니다.

저에게 있어, 그것이 에이전트에게 무언가를 요청하는 것과 명세서(specs)를 가지고 작업하는 것 사이의 결정적인 차이입니다.

Harness를 그대로 복제하지 않더라도 그 형태는 복제할 수 있습니다. 문제, 제약 조건, 사용자 흐름(user flow), 비목표(non-goals), 수락 기준(acceptance criteria), 그리고 이미 알고 있는 기이한 엣지 케이스(edge cases)들을 적어 내려가세요. 그것만으로도 에이전트가 (잘못된 정보를) 확신을 가지고 채워버릴 수 있는 수많은 모호함(ambiguity)을 제거할 수 있습니다.

오후의 낮잠

오후의 첫 번째 낮잠 시간 동안, 에이전트가 생성한 코드를 검토할 시간입니다.

저는 각 워크트리(worktree)에서 코드 리뷰를 실행합니다. 만약 무언가 발견되면 수동으로 검토하고 테스트하며, 마음에 들지 않는 부분이 있으면 에이전트에게 수정을 지시합니다. 모든 것이 정돈되면, PR(Pull Request)이나 다른 절차 없이 곧바로 main 브랜치에 머지(merge)합니다. 완전히 YOLO 스타일로 말이죠. 어쨌든 이 프로젝트들은 저 혼자 작업하는 개인 프로젝트니까요.

그렇다고 리뷰가 없다는 뜻은 아닙니다. 저는 리뷰가 작업의 핵심적인 부분이라는 점을 점점 더 확신하고 있습니다. 다만 리뷰가 항상 PR을 열고 체크(checks)를 기다리는 모습으로 나타나지는 않을 뿐입니다. 이 프로젝트들에서 리뷰란 제가 흐름을 테스트하고, 디프(diff)를 읽고, 이상한 가설을 포착하며, 결과물이 여전히 원래의 의도와 일치하는지 결정하는 과정입니다.

마지막으로 모든 것이 통합되면, 프로젝트 문서, README, 그리고 Harness 명세서(specs)가 코드와 동떨어지지 않도록 /update-docs를 실행합니다.

에이전트(agents)와 함께 진행하는 프로젝트의 통제력을 잃는 가장 빠른 방법 중 하나는 문서화(documentation)가 뒤처지게 방치하는 것입니다. 만약 다음 세션이 오래된 컨텍스트(context)로 시작된다면, 에이전트는 더 이상 존재하지 않는 현실을 바탕으로 작업을 수행하게 될 것입니다.

그리고 그 이후에는요? 음, 아직 일어나지 않았다면 아마 기저귀를 갈아줘야 하거나, 같이 놀아줘야 하거나, 침을 흘리고 옹알이를 하는 상황이 기다리고 있겠죠... 솔직히 말해서, 저는 이 아기에게 완전히 빠져 있습니다.

프로그래밍처럼 느껴지지 않는다

소프트웨어 엔지니어링(software engineering)에 접근하는 이 새로운 방식은 프로그래밍처럼 느껴지지 않습니다. 그리고 그것이 반드시 나쁜 것만은 아닙니다.

코드(Code)는 더 저렴하고, 빨라졌으며, 접근하기 쉬워졌지만, 제 관점에서는 아이디어, 취향, 본능, 그리고 고차원적인 지식(high-level knowledge)이 현재 가장 가치 있는 것들입니다. 무엇을 만들려고 하는지 명확하지 않다면, 평범한 수준의 코드를 빠르게 대량으로 생성하는 것은 매우 쉽습니다.

이런 방식으로 작업함으로써 저는 이전에는 할 수 없었던 방식으로 앞으로 나아갈 수 있었고, 사실상 죽어있던 프로젝트들을 다시 살려낼 수 있었으며, 동시에 아이와 함께 시간을 보낼 수 있었습니다. 물론 항상 잘 풀리는 것만은 아닙니다. 모호한 명세서(specs), 숨겨진 컨텍스트(context), 그리고 롤백(rollback)해야만 했던 잘못된 구현들 때문에 좋지 않은 경험을 하기도 했습니다.

하지만 바로 그 지점에서 저는 가장 많은 것을 배웠습니다.

명세서(specs)를 진지하게 다루는 것은 미적인 결정이나 유행을 따르는 것이 아니었습니다. 그것은 한 단계 더 높은 차원으로 올라가, 제품(product)과 아키텍처(architecture)의 역할을 수행하며, 단 한 번의 낮잠 시간만이 남아있는 상황에서도 견고한 무언가를 만들어내기 위한 방법이었습니다.