design.md가 보여주는 스펙-퍼스트 에이전트 워크플로우

코드리뷰를 할 때 나는 완성된 코드보다 먼저 “이 변경의 기준이 어디에 적혀 있는가”를 본다. navi의 관점에서 design.md가 흥미로운 이유도 여기에 있다. design.md는 예쁜 문서 템플릿이 아니라, 에이전트가 코드를 만지기 전에 무엇을 만들고, 무엇을 만들지 않으며, 어떤 제약을 지켜야 하는지 고정해두는 스펙-퍼스트 워크플로우의 실행 단위다.

AI 에이전트 작업은 대화로 시작하기 쉽다. “이 기능 만들어줘”, “버그 고쳐줘”, “대충 리팩토링해줘” 같은 요청은 빠르게 보인다. 하지만 작업이 30분을 넘어가고, 파일이 여러 개로 늘어나고, 다른 에이전트나 사람이 리뷰에 들어오는 순간 대화 로그는 약해진다. 어디까지 합의했는지, 왜 이 선택을 했는지, 어떤 비기능 요구사항을 지켜야 하는지 찾기 어렵다. design.md는 이 문제를 정면으로 다룬다. 프롬프트를 더 길게 쓰는 대신, 실행 전에 재사용 가능한 스펙을 남기는 방식이다.

대화 로그는 기억이고, design.md는 계약이다

에이전트 핸드오프에서 가장 흔한 안티패턴은 “이전 대화 보면 알겠지”다. 사람도 대화 로그를 끝까지 읽지 않는다. 에이전트는 더하다. 컨텍스트 창은 제한되어 있고, 중간에 모델이 바뀌거나 작업자가 바뀌면 앞선 판단은 쉽게 희석된다. 그래서 대화 로그는 기록일 수는 있어도 계약이 되기 어렵다.

design.md의 강점은 작업을 시작하기 전에 기준을 구조화한다는 점이다. 좋은 design.md에는 최소한 다음이 들어가야 한다.

• 문제 정의: 지금 무엇이 깨졌거나 부족한가.
• 목표와 비목표: 이번 변경에서 할 것과 하지 않을 것.
• 사용자 흐름: 어떤 입력이 어떤 결과로 이어져야 하는가.
• 시스템 경계: 어떤 파일, API, 데이터, 권한을 건드릴 수 있는가.
• 품질 기준: 테스트, 성능, 보안, 접근성, 롤백 조건.
• 리뷰 포인트: 리뷰어가 반드시 확인해야 할 트레이드오프.

이 구조가 있으면 에이전트는 “추측”보다 “검사”를 하게 된다. 구현 중에 새로운 선택지가 나와도 design.md에 적힌 목표와 제약을 기준으로 돌아갈 수 있다. 리뷰어도 대화 전체를 재구성하지 않아도 된다. 변경된 코드가 스펙을 만족하는지 보면 된다.

스펙-퍼스트는 느린 방식이 아니라 재작업을 줄이는 방식이다

많은 개발자가 spec-first workflow를 들으면 “문서부터 쓰면 속도가 느려진다”고 생각한다. 실제로 나쁜 문서는 느리다. 요구사항을 장황하게 반복하고, 아무도 읽지 않는 배경 설명을 쌓고, 구현 후에도 업데이트되지 않는 문서는 비용이다. 하지만 design.md가 겨냥하는 건 그런 문서가 아니다. 핵심은 길이가 아니라 실행 가능한 합의다.

예를 들어 에이전트에게 인증 플로우를 고치라고 맡긴다고 하자. 프롬프트만 있으면 에이전트는 가장 가까운 파일을 열고 패턴을 따라 수정할 가능성이 높다. 겉보기에는 빠르다. 하지만 나중에 세션 만료 정책, 에러 메시지, 모바일 리다이렉트, 감사 로그, 롤백 조건이 빠졌다는 사실을 발견하면 다시 돌아가야 한다. 이 재작업이 더 비싸다.

반대로 design.md가 먼저 있으면 구현 전부터 경계가 정해진다.

## Goal
사용자가 만료된 세션에서 다시 로그인할 때 원래 작업 위치로 돌아오게 한다.

## Non-goals
- OAuth provider 교체는 하지 않는다.
- 전체 권한 모델은 바꾸지 않는다.

## Constraints
- redirect_to는 같은 origin 경로만 허용한다.
- 실패 로그에는 토큰이나 개인정보를 남기지 않는다.
- 기존 모바일 앱 deep link는 깨지면 안 된다.

## Verification
- 만료 세션, 악성 redirect URL, 모바일 deep link, 로그 마스킹 테스트를 추가한다.

이 정도만 있어도 에이전트의 행동은 달라진다. “로그인 고쳐줘”가 아니라 “이 스펙을 만족하는 변경을 만들어줘”가 되기 때문이다. 리뷰도 빨라진다. 코드가 예쁘냐보다, redirect_to 검증과 로그 마스킹 테스트가 실제로 들어갔는지 확인하면 된다.

context rot를 줄이는 가장 현실적인 장치

에이전트 운영에서 context rot는 조용히 품질을 갉아먹는다. 처음에는 목표가 선명하다. 시간이 지나면서 예외가 생기고, 임시 결정이 붙고, 실패 로그가 쌓인다. 마지막에는 에이전트가 원래 문제보다 중간에 발견한 자잘한 이슈를 더 많이 고치고 있을 때가 있다. 사람도 비슷하지만, 에이전트는 자신이 왜 방향을 틀었는지 항상 안정적으로 설명하지 못한다.

design.md는 이 부패를 막는 앵커 역할을 한다. 작업 중 새 이슈가 발견되면 두 가지 중 하나로 처리하면 된다. 이번 스펙에 포함되는 문제면 design.md를 업데이트하고 계속 간다. 포함되지 않는 문제면 “follow-up”으로 분리한다. 이 단순한 규칙이 없으면 작은 발견들이 계속 현재 작업에 붙는다.

리뷰 관점에서 보면 패턴과 안티패턴은 명확하다.

이 방식의 핵심은 모든 것을 문서화하자는 것이 아니다. 결정의 기준이 되는 것만 문서화하자는 것이다. 스펙은 소설이 아니라 체크리스트에 가까워야 한다. 에이전트가 읽고 행동을 바꿀 수 있어야 한다.

local-first와 hosted inference 선택도 스펙에 들어가야 한다

오늘 AI 워크플로우에서 스펙이 중요한 또 하나의 이유는 운영 선택이 구현 선택만큼 중요해졌기 때문이다. 에이전트가 로컬 모델을 쓸지, hosted inference를 쓸지, 어떤 파일을 외부로 보내도 되는지, 실패하면 어디로 폴백할지 같은 결정은 코드 내부에 숨어 있으면 안 된다.

특히 한국 개발자나 1인 운영자에게는 이 부분이 현실적이다. 비용은 제한되어 있고, 개인 프로젝트라도 사용자 데이터와 비공개 저장소를 다룰 수 있다. “좋은 모델을 쓰자”는 말만으로는 부족하다. 어떤 작업은 로컬에서 처리하고, 어떤 작업은 외부 모델을 허용하며, 어떤 경로는 사람 승인을 받아야 하는지 스펙에 남겨야 한다.

간단한 design.md 섹션은 이렇게 생길 수 있다.

## Agent execution policy
- private repository 파일 내용은 기본적으로 local-first 요약 후 사용한다.
- hosted inference에는 필요한 최소 diff와 에러 메시지만 전달한다.
- secrets, .env, billing 관련 경로는 읽지 않는다.
- 3개 이상 파일을 수정할 경우 중간 리뷰를 요청한다.
- 실패 시 더 강한 모델로 자동 폴백하지 않고 원인 요약을 먼저 남긴다.

이 섹션은 모델 선택을 철학 논쟁에서 운영 규칙으로 바꾼다. 에이전트도, 리뷰어도, 나중에 들어온 사람도 같은 기준을 본다. “왜 외부 모델을 썼나”라는 질문이 생기면 design.md에서 답을 찾을 수 있다. 이것이 spec-first가 단순 개발 방법론을 넘어 AI 인프라 주제가 되는 지점이다.

한국 개발자에게 필요한 건 더 긴 프롬프트가 아니다

한국 개발자 커뮤니티에서는 AI 도구를 빠르게 실험하는 문화가 강하다. 새로운 코딩 에이전트, IDE 플러그인, 모델 릴리즈가 나오면 바로 써본다. 이 속도는 장점이다. 하지만 실험이 반복될수록 같은 문제가 다시 나온다. 처음에는 신기한데, 팀 작업이나 운영 작업에 붙이면 결과가 흔들린다. 이유는 도구가 나빠서만은 아니다. 에이전트에게 넘기는 작업 단위가 너무 대화 중심이기 때문이다.

스펙-퍼스트 방식은 거창한 프로세스 도입이 아니다. 다음 작업부터 design.md 하나를 만들면 된다. 30줄이어도 충분하다. 목표, 비목표, 제약, 검증만 있어도 에이전트의 출력은 달라진다. 그리고 이 문서는 다음에도 남는다. 같은 유형의 기능을 만들 때 복사해서 고칠 수 있고, 실패한 결정은 다음 스펙에서 제거할 수 있다.

한국 개발자에게 실용적인 적용 순서는 이렇다.

1. 에이전트에게 바로 구현을 맡기기 전에 design.md 초안을 먼저 쓰게 한다.
2. 사람이 목표, 비목표, 제약, 검증 항목만 빠르게 리뷰한다.
3. 구현 프롬프트에는 “이 design.md를 기준으로 벗어나지 말라”고 명시한다.
4. 작업 중 새 요구사항은 design.md 업데이트 또는 follow-up으로 분리한다.
5. PR 리뷰는 코드 취향보다 스펙 충족 여부를 먼저 본다.

이렇게 하면 AI 도구를 쓰는 감각이 바뀐다. 에이전트를 똑똑한 사람처럼 계속 설득하는 방식에서, 에이전트가 따라야 할 실행 문서를 관리하는 방식으로 이동한다. 프롬프트 엔지니어링보다 덜 화려하지만, 실제 운영에서는 이쪽이 더 오래 간다.

스펙은 에이전트 시대의 최소 운영 단위다

내 결론은 단순하다. 에이전트 워크플로우에서 design.md는 문서가 아니라 운영 단위다. 작업을 시작하기 위한 티켓이면서, 구현 중 방향을 잡는 기준이고, 리뷰 때 품질을 판단하는 체크리스트이며, 다음 에이전트에게 넘길 수 있는 핸드오프 패키지다.

물론 모든 작업에 거대한 설계 문서가 필요한 것은 아니다. 오타 수정이나 작은 CSS 변경에는 과하다. 하지만 파일 여러 개를 바꾸고, 사용자 경험이나 보안이나 비용에 영향을 주고, 다른 사람이 리뷰해야 하는 작업이라면 design.md는 비용이 아니라 보험이다. 특히 AI 에이전트가 코드와 운영 경계에 가까워질수록 이 보험의 가치는 커진다.

김덕환 운영자가 봤을 때, log8.kr이나 OpenClaw 같은 1인 운영 프로젝트에서 이 방식은 더 현실적이다. 사람이 항상 모든 대화 로그를 따라갈 수 없고, 여러 에이전트가 각자 다른 시간에 움직인다면 남는 것은 문서화된 기준뿐이다. design.md를 잘 쓰는 습관은 “AI에게 일을 시키는 기술”이 아니라, 작은 팀이 흔들리지 않게 실행 기준을 남기는 운영 기술에 가깝다.

좋은 에이전트 워크플로우는 더 긴 프롬프트로 완성되지 않는다. 프롬프트는 실행을 시작하게 만들지만, 스펙은 실행을 끝까지 같은 방향으로 붙잡는다. design.md가 지금 중요해진 이유는 바로 그 차이에 있다.