Spec Anchor Development: 우리의 AI 혼돈을 대체한 방법론

이것은 우리가 모두가 각자의 방식으로 AI를 사용하던 팀에서, 일관되고 검토 가능하며 온보딩(onboardable)이 가능한 코드베이스를 가진 팀으로 변화한 과정입니다. 세 가지 방법론, 6개월의 시간, 그리고 실제로 정착된 단 하나의 방법론입니다.

"모두가 각자의 방식으로 AI를 사용한다"는 문제점
AI 코딩 도구들이 성능이 좋아지기 시작했을 때, 우리 팀은 대부분의 팀이 그러하듯 사람들이 스스로 알아서 하도록 내버려 두었습니다. 시니어, 미드 레벨, 두 명의 신입 사원까지 모두가 자신만의 워크플로우(workflow)를 가지고 있었고, 모두가 결과물을 내놓고 있었지만, 누구도 동일한 종류의 코드를 생산하지 않았습니다.

균열은 리뷰 과정에서 나타났습니다. 어떤 PR(Pull Request)은 프로젝트 컨벤션(convention)을 완전히 무시했습니다. 다른 것들은 기술적으로는 맞았지만, 우리가 겪고 있지 않은 성능 문제에 대해 AI가 최적화하느라 코드가 비대해진 경우도 있었습니다. 커밋 히스토리(commit history)는 노이즈로 가득했습니다. 가장 많은 구조화가 필요했던 주니어 개발자들은 AI가 제공한 결과물이 실제로 좋은 것인지 판단할 수 있는 맥락(context)이 가장 부족했습니다.

이것은 사실 AI의 문제가 아닙니다. 공유된 표준이 없는 팀에게 전동 공구를 건네주며 잘될 것이라고 가정할 때 발생하는 현상입니다.

1단계: 규칙(Rules)
첫 번째 해결책은 가장 간단했습니다. 당시에는 Cursor가 지배적인 도구였으며(이는 에이전트 모드, Codex, Claude Code가 나오기 전이었습니다), Cursor에는 규칙 시스템이 있었습니다. 저는 하루를 투자해 명명 규칙(naming conventions), 커밋 형식(commit format), 복잡도 제한, 이미 확인된 안티 패턴(anti-patterns), 그리고 무엇이 좋고 나쁜지에 대한 예시를 포함한 실제 규칙 세트를 작성했습니다.

대상 리포지토리(repo)에서 이는 즉각적인 효과를 보였습니다. PR이 더 일관되게 작성되었고, 리뷰 속도도 빨라졌습니다. 알아둘 만한 기술 하나는, AI에게 자신의 출력물을 규칙과 비교하여 일탈 사례를 표시하도록 요청하는 것입니다. 이는 가벼운 품질 게이트(quality gate)로서 잘 작동합니다.

참고할 점은, 이것이 Cursor만의 기능이 아니라는 것입니다. 오늘날 모든 진지한 AI 코딩 도구에는 그에 상응하는 기능이 있습니다. Claude Code에는 CLAUDE.md가 있고, Windsurf에는 rules가 있으며, Copilot에는 instructions가 있고, Gemini Code Assist에는 context files가 있습니다. 메커니즘은 다르지만 원칙은 같습니다. 공유된 규칙을 작성하여 프로젝트에 넣어두면, 모든 도구를 사용하는 모든 개발자가 그 혜택을 입습니다.

하지만 한계점은 꽤 빨리 명확해졌습니다. 규칙은 스타일과 구조를 제어할 뿐입니다.

개발자가 단 한 번의 프롬프트(prompt)로 전체 기능을 구축해 달라고 AI에게 요청할 때는 이러한 규칙들이 도움이 되지 않습니다. 이는 비대해진 컨텍스트 (context), 저하된 일관성 (coherence), 그리고 작업 도중에 맥락을 놓쳐버리는 출력 결과로 이어집니다.

두 번째 단계: SpecKit. SpecKit은 그 무렵 등장했습니다. 전제 조건은 코드를 작성하기 전에 작업을 개별적인 명세 (spec)로 나누는 것이었습니다. 이를 통해 AI가 개방형 기능 요청 대신, 작고 잘 정의된 단위들을 처리하도록 만드는 것입니다. 저는 일주일 동안 직접 테스트하여 좋은 결과를 얻었고, 이를 우리의 AI 지원 리포지토리 (repos)에 도입했습니다.

그 후, 오버헤드 (overhead)가 문제가 되었습니다. SpecKit의 단계 수는 우리에게 필요한 것보다 많았습니다. 기능이 추가될 때마다 계속 늘어나는 목록에 새로운 명세가 추가되었습니다. 몇 달이 지나자 그것은 그저 미화된 계획 모드 (plan mode)처럼 느껴졌습니다. 목록은 존재했지만, 기능이 출시된 후에는 아무도 참조하지 않았으며, 제품 수준의 결정 사항과도 연결되어 있지 않았습니다. 신입 엔지니어들은 무언가가 왜 특정한 방식으로 구축되었는지 이해하기 위해 이를 활용할 수 없었습니다. 우리는 문서를 생성하고 있었을 뿐, 지식을 포착하고 있었던 것이 아니었습니다.

왜 Spec Anchor Development인가? 추가적인 연구 끝에 저는 SDD (Specification-Driven Development, 명세 주도 개발)의 변형인 Spec Anchor Development를 발견했습니다. 여기서 명세는 체크리스트의 한 단계가 아닙니다. 그것은 빌드 전에 작성되고, 빌드 중에 사용되며, 빌드 후에도 참조용으로 유지되는 지속적인 산출물 (artifact)입니다. 이것이 SpecKit과의 실제적인 차이점입니다. SpecKit에서는 명세가 축적됩니다. Spec Anchor Development에서는 각 명세가 특정 기능이나 결정에 결합되어 있어, 나중에 실제로 읽을 수 있을 만큼 가볍습니다.

실제 상황에서 Spec Anchor가 하는 역할:

• AI가 무엇인가를 건드리기 전에 개발자(AI가 아님)가 무엇을 구축할지 정의합니다.
• AI는 제한된 범위 (bounded scope)를 할당받습니다: 추측이나 범위 확장 (scope creep)이 발생하지 않습니다.
• 누군가 "왜 이것이 이런 방식으로 구축되었나요?"라고 물을 때, 이에 답하는 문서가 존재합니다.
• 결정 사항이 더 넓은 시스템에 영향을 미칠 때, 이는 ADR (Architecture Decision Record, 아키텍처 결정 기록)로 이어집니다.

마지막 항목은 제가 예상했던 것보다 더 많은 것을 변화시켰습니다. Spec Anchor와 함께 ADR을 생성하거나 업데이트하도록 시스템을 구성하자, 우리는 조직의 지식을 잃어버리는 것을 멈출 수 있었습니다. 신입 엔지니어들은 결정의 흔적 (decision trail)을 읽을 수 있게 되었습니다.

시니어 엔지니어들은 매번 코드 리뷰 (code review)를 할 때마다 동일한 아키텍처 컨텍스트 (architectural context)를 다시 설명해야 하는 상황을 멈출 수 있었습니다. OpenSpec은 Spec Anchor Development를 위한 주요 도구입니다. 이것이 다양한 숙련도를 가진 팀에서 효과를 발휘하는 이유는 너무 많은 것을 하려고 하지 않기 때문입니다. 스펙 템플릿 (spec template)은 필요한 것만 포함하고 그 이상은 하지 않습니다. 개발자들이 스펙을 작성하는 것을 싫어하지 않을 만큼 충분히 빠르며, 누가 작성하든 팀 전체에서 결과물이 일관되도록 충분히 구조화되어 있습니다. 우리는 전체 설정 (ADR 생성을 포함한 OpenSpec)을 3개월 동안 운영했습니다. 실제로 변화를 가져온 몇 가지 사항은 다음과 같습니다:

• 코드 품질이 시니어 소유의 저장소 (repos)뿐만 아니라 모든 숙련도 수준에서 일관되게 유지되었습니다.
• 의무적인 스펙 단계는 개발자들이 코딩하기 전에 속도를 늦추도록 강제했습니다. 이것이 마찰 (friction)처럼 들릴 수도 있습니다. 하지만 이는 코드 문제로 이어질 수 있었던 범위 (scope) 문제를 사전에 잡아냈습니다. 결과적으로는 순이익 (Net positive)이었습니다.
• 제품 (Product) 팀과 엔지니어링 팀 모두 별도의 번역 없이 스펙 계층 (spec layer)을 읽을 수 있었습니다.
• 온보딩 (Onboarding)이 쉬워졌습니다. 신입 엔지니어들은 코드를 읽기 전에 스펙과 ADR을 읽고, 실제적인 컨텍스트를 가진 상태로 업무에 투입되었습니다.

만약 여러분이 유사한 시스템을 구축하려 한다면, 여기서 얻어야 할 교훈은 다음과 같습니다:

• 규칙을 먼저 세우되, 그것이 확장될 것이라고 기대하지 마세요. 팀이 어떤 도구를 사용하든, 거의 확실하게 규칙이나 지침 (instructions) 시스템을 갖추고 있을 것입니다. 그것을 사용하세요. 그것은 가능한 가장 빠른 승리이며, 다른 무엇을 채택하든 상관없이 실행할 가치가 있습니다. 그것이 기능 범위 (feature-scoping) 문제를 해결해주지는 않을 것입니다. 해결하도록 설계된 것도 아닙니다.
• 배포하기 전에 테스트하세요. 방법론을 팀에 적용하기 전에 일주일 동안 개인적인 평가를 수행하세요. 잘못된 방법론으로 인해 팀이 치러야 하는 비용 (team tax)은 실재하며, 이를 되돌리는 데는 오랜 시간이 걸립니다.

SpecKit이 모든 팀에게 틀렸던 것은 아닙니다. 우리 팀에게 틀렸을 뿐입니다. 스펙은 티켓 (ticket)이 아닙니다. 잘 작성된 스펙 앵커 (spec anchor)는 AI가 무엇을 구축하고 무엇을 구축하지 않는지를 정의합니다. 그 제약 조건이 바로 대부분의 팀이 대규모 기능 구현 시 겪는 "거대한 프롬프트, 저하된 출력 (huge prompt, degraded output)" 실패를 막아주는 핵심입니다. 계획을 세우는 습관은 AI 워크플로우 (workflow)보다 더 중요합니다. 이 시스템이 해낸 가장 좋은 일은 개발자들이 에디터를 열기 전에 생각하는 방식을 바꾼 것입니다.

스펙 (spec) 단계에 시간을 할애하는 것은 범위 (scope), 예외 케이스 (edge cases), 그리고 의도 (intent)에 대해 실제로 고민하도록 강제했습니다. AI는 단지 그 습관을 체계적으로 만들어 주었을 뿐입니다. ADR (Architecture Decision Records)을 건너뛰지 마세요. 만약 스펙이 왜 그런 결정이 내려졌는지에 대한 기록과 연결되지 않는다면, 여러분은 매번 회고 (retro)를 할 때마다, 그리고 새로운 팀원이 합류 (onboarding)할 때마다 그 맥락을 처음부터 다시 재구성해야 할 것입니다. 이는 팀들이 가장 먼저 건너뛰지만, 가장 크게 후회하는 부분입니다.