개발자는 문서를 업데이트하지 않습니다. 의지가 없어서가 아니라, 사람이 원래 그렇게 설계되어 있지 않아서입니다.

AI 코딩 도구 Augment Code가 자사 신제품 Intent를 소개하며 흥미로운 문제를 짚었습니다. 에이전트 기반 개발에서 spec(명세서)을 쓰는 것 자체는 좋은 아이디어지만, 사람이 그걸 최신 상태로 유지해야 한다면 결국 실패한다는 겁니다.

출처: What spec-driven development gets wrong – Augment Code

“100% 믿을 수 있는 문서는 코드뿐이다”

설계 문서, README, 아키텍처 다이어그램. 이 문서들은 작성하는 순간부터 낡기 시작합니다. 개발자는 기능을 만들고, 배포하고, 다음 일로 넘어갑니다. 문서를 업데이트하는 일은 아무도 알아채지 못하고 아무도 보상하지 않는 ‘보이지 않는 작업’입니다. 프로세스를 만들어도, 도구를 도입해도, 팀 문화로 만들려 해도 잘 되지 않는 이유가 여기 있습니다.

AI 에이전트와 함께 개발할 때 이 문제는 훨씬 심각해집니다. 낡은 설계 문서는 나중에 읽는 개발자를 잠깐 헷갈리게 할 뿐이지만, 낡은 spec은 에이전트를 엉뚱한 방향으로 확신에 차서 달리게 만듭니다. 에이전트는 “이 가정이 잘못된 것 같은데요”라고 먼저 말하지 않습니다.

spec이 스스로를 유지한다면?

Augment는 Intent를 만들면서 이 질문을 던졌습니다. 사람이 spec을 관리하는 게 아니라, spec이 스스로 최신 상태를 유지할 수 없을까?

작동 방식은 이렇습니다. 개발자가 만들고 싶은 것을 설명하면, 코디네이터 에이전트가 spec 초안을 작성하고 작업을 세부 태스크로 나눕니다. 개발자가 검토하고 승인하면 에이전트들이 작업을 시작합니다. 그리고 작업 중에 발견한 내용(예상과 달랐던 부분, 변경한 결정, 맞닥뜨린 제약 등)을 에이전트가 직접 spec에 기록해 돌려줍니다.

Augment는 이를 좋은 주니어 엔지니어에 비유합니다. 좋은 주니어는 API가 티켓의 가정과 다르게 동작한다는 걸 발견하면, 조용히 잘못된 걸 구현하거나 눈치채길 기다리지 않습니다. 직접 티켓을 수정하고 “이 가정이 틀렸고, 대신 이렇게 했습니다”라고 알려줍니다. Intent는 에이전트가 그 역할을 하도록 설계했습니다.

중요한 건 어느 수준의 업데이트를 올려 보내느냐입니다. 코드 한 줄 한 줄을 다 보고하면 노이즈가 되고, 너무 적으면 무슨 일이 있었는지 알 수 없습니다. “기존 theme context provider를 발견해서 새 store 대신 거기 연결했습니다” 같은, 방향을 바꾼 결정만 surfacing하는 것이 핵심입니다.

문서화 우선 방식이 반복해서 실패한 이유

Augment가 지적하는 핵심은 단순합니다. 소프트웨어 업계에서 ‘문서화 우선’ 시도가 계속 실패해온 건 모두 같은 이유, 즉 아무도 보지 않고 아무도 보상하지 않는 유지 작업을 사람에게 요구했기 때문입니다. spec 기반 개발도 에이전트가 유지 작업의 몫을 나눠 갖지 않으면 같은 운명이 될 것이라는 게 이들의 주장입니다.

에이전트가 코드를 쓸 수 있다면, 계획도 업데이트할 수 있습니다. Intent는 그 아이디어를 제품으로 구현한 첫 시도 중 하나입니다. 현재 macOS(Apple Silicon)에서 공개 베타로 사용 가능하며, 자세한 내용은 원문에서 확인할 수 있습니다.

참고자료: Intent: A workspace for agent orchestration – Augment Code