6~9개월 동안 혼자 개발한 대형 소프트웨어 두 개에 OpenSpec을 폭넓게 사용했지만, 최근에는 명세 작성 부분을 완전히 버림. 장기적으로 유용하지 않았고, LLM으로 코드와 명세가 서로 일치하는지 양방향으로 검사하니 두 프로젝트 모두 큰 괴리가 드러남. 결국 코드 자체가 명세라는 오래된 이론이 맞는 셈임.
반면 제안 작성 → 제안 검토 → 구현 → 코드 검토라는 절차는 매우 유용해서 유지함. 아키텍처 결정 기록(ADR)과 단위 테스트로 검증할 수 없는 동작의 불변 조건 기록도 유용함. 이런 절차와 기록, 단위 테스트가 서로 연결되지 않은 여러 컨텍스트에서 LLM이 계속 작업하더라도 소프트웨어의 일관성을 지켜줌.

명세는 내가 직접 쓰는 것이고, 코드는 LLM이 대신 쓰는 것임. 명세의 형식은 원하는 상세 수준에 따라 무엇이든 될 수 있음.
LLM 시대에 “코드가 명세”라는 접근이 곤란한 이유는 LLM이 당장의 목표를 달성하면서 알리지 않고 다른 부분까지 바꾸기 때문임. 6개월 전에는 모든 변경을 직접 검토했지만, 이제는 LLM으로 코드가 명세와 일치하는지 감사함. 차이가 있다면 내가 명세를 수정하거나 LLM이 코드를 수정해야 함.

몇 달간 OpenSpec을 폭넓게 써보니 저장소에 오래 남는 명세는 쓸모가 없지만, OpenSpec의 변경 절차는 매우 유용함. 대규모 코드베이스에 복잡한 새 기능을 추가하는 것처럼 하나의 복잡한 작업에서 에이전트가 방향을 잃지 않도록 해줌.

코드는 명세의 일부일 뿐임. 의사결정의 근거로 삼을 만큼 실제 요구사항을 충분히 담는 경우는 드묾. 코드가 스스로 설명해야 한다고 해도, 주로 드러내는 것은 구현상의 이유이지 요구사항 자체의 배경은 아님. 이 부분에서는 OpenSpec이 상당히 도움이 됨.

문서가 전부 사용법, 스킬 관리, 설정 방법에 관한 내용임. 내가 보고 싶은 것은 이 도구가 무엇이고, 어떻게 작동하며, 왜 효과가 있는지에 대한 설명이고, 가능하면 벤치마크도 필요함. 그렇지 않으면 결과를 알 수 없는 또 다른 스킬 묶음으로만 보임.

이것이 1990년대의 UML 코드 생성과 어떻게 다르고, 왜 같은 방식으로 실패하지 않을지 설명해 줄 수 있을까?
내 경험상 이런 도구가 작동하지 않는 주된 이유는 명세와 코드의 괴리임. 새 프로젝트에서 기능을 한 번에 생성할 때는 통할지 몰라도, 여러 개발자가 오랫동안 유지하는 대규모 코드베이스에서는 명세가 낡아 오히려 부담이 커짐.

왜 명세와 코드가 어긋나도록 두는지 궁금함. 우리 팀은 AI 검토로 기존 명세와 현재 구현을 대조하고, 충돌이 있으면 풀 리퀘스트 검토에 표시해 수정함. 둘을 동기화하는 데 매우 유용하고 잘 작동함.

적어도 Rational 등이 주도한 주류 UML은 여러 이유로 실패했는데, 여기서는 두 가지가 특히 관련됨.
첫째, 명세와 실행 코드 사이의 피드백 순환이 없었음. Rational Unified Process(RUP)는 수작업이 많고 매우 비효율적이었으며, 플랫폼 독립 모델과 플랫폼 종속 모델 같은 산출물의 대응 관계도 주로 사람이 경험칙으로 관리함. 프로젝트가 발전해도 모델은 대체로 갱신되지 않았음.
둘째, 개발 방식과 도구의 사용자 경험이 맞지 않았음. 코드를 쓰는 대신 다이어그램을 만들도록 요구했고, 도구는 “마우스로 코드 쓰기”에 가까웠으며, 산출물도 변경 비교나 소스 버전 관리에 잘 맞지 않았음. XML 파일을 텍스트로 비교해 보면 알 수 있음.
코딩 에이전트는 결과 코드를 읽고 어느 정도 명세와 동기화할 수 있어 첫 번째 문제를 완화할 가능성이 있음. 두 번째는 더 불확실함. 코드 설계·작성보다 문제 해결에 관심이 큰 사용자는 자연어 명세와 탐색을 편하게 느끼겠지만, 코드에 익숙한 개발자는 이를 UML 다이어그램처럼 본질에서 벗어난 방해물로 볼 수 있음.

사람이 명세가 바뀌었다고 명시하면서 코드 수정을 지시하면, 에이전트가 명세도 찾아서 갱신한다는 전제인 듯함. 다만 내가 기대하는 동작을 투영하며 능력을 과대평가하는 것일 수도 있음.

프로젝트의 변화를 추적해야 한다는 우려는 여기에도 적용됨. 다만 계획과 실행을 위한 표준화된 구조를 제공하므로, 이를 중심으로 에이전트 코딩 절차와 반복 작업을 구성할 수 있다는 장점도 있음.

이제 이런 도구를 넘어설 때가 되지 않았을까? 최신 LLM은 긴 컨텍스트 작업을 충분히 학습해 계획 수립에 꽤 능숙해졌고, 실행 환경의 도움도 있을 수 있음. 어느 쪽이든 Codex나 Claude Code를 쓴다면 굳이 도입하지 않을 것 같음.

주로 OpenSpec 대신 speckit을 쓰지만, 기본적으로 같은 종류의 도구라고 봄. 사용하는 이유 중 하나는 나와 LLM 모두에게 작업 규율을 강제하기 위해서임. 그렇지 않으면 같은 자리를 맴돌기 쉽고, 이런 도구는 토큰 절약에도 도움이 됨. 핵심은 명확한 산출물과 규율임. LLM만으로도 할 수 있고 실제로 그렇게 했지만, 매우 어수선했음.

계획을 세울 수 있다고 해서 원하는 결과를 만든다는 보장은 없음. 무엇을 만들지 합의하는 작업이 대부분을 차지하기도 하고, 아직 기술 계획까지 전부 맡길 생각은 없음.
이 스킬로 명세를 점진적으로 구체화함. 무엇을 만들지는 사람이 주도하고, 상위 수준 기술 계획은 반반씩 맡으며, 세부 구현에서는 질문이 생길 때만 사람이 관여함. https://github.com/scosman/vibe-crafting.

긴 컨텍스트 작업을 충분히 학습해서 계획 수립에 능숙해졌다는 전제는 전혀 사실이 아님.

개인이나 조직이 선호하는 해결 방식은 LLM의 기본 방식과 크게 다를 수 있음. 나는 선호하는 설계·작업 방식을 명세에 담음. 예를 들어 대부분의 LLM은 구현한 것뿐 아니라 구현하지 않은 것까지 문서화하려 하며, 해결 방식을 바꾸거나 작은 마이그레이션을 한 뒤에는 특히 심해짐. 명세로 이런 행동의 상당 부분을 바로잡을 수 있음.

나도 그렇게 생각함. 예전에 speckit을 꽤 써봤지만 결과는 좋게 봐도 엇갈렸음. 모호함과 코드 검토의 위치만 옮길 뿐, 실질적으로 얻는 것이 없었음.

OpenSpec은 처음 보는데, 올해 내가 만들고 있는 도구와 철학이 비슷해 보임. 이런 접근이나 명세 주도 개발(SDD)에 관심이 있다면 피드백을 부탁함. https://github.com/spekk-ai/spekk-cli
명세를 반복적으로 다듬는 철학은 비슷하지만, 우리는 선언적 명세와 설치 가능한 에이전트 스킬에 집중함. 단순성과 최소한의 실행 요건을 위해 Go를 선택했으며, 단일 바이너리로 배포함.

비난하려는 뜻은 아니고, 이런 부분에 서툴러서 정말 궁금함. 비슷한 프로젝트를 1년째 만들면서 OpenSpec은 처음 봤다고 했는데, OpenSpec과 Speckit도 거의 같은 목표를 가진 것처럼 보임. 이미 있는 유사 도구는 크게 신경 쓰지 않고 시작하는 편인지 궁금함. 나는 이런 걸 지나치게 고민하는 경향이 있음.

나도 비슷한 것을 만들었는데, 이쪽이 더 깔끔해 보임. 내 도구에는 ‘컴파일러’와 S식 기반 DSL이 있음. 5만 줄이 넘는 중대형 프로그램을 어떻게 바이브 코딩하는지 모르겠음. 나도 뭔가 어긋났다는 느낌이 들기 전에는 명세를 전부 읽지는 않음.
너무 복잡하게 만든 게 아닌가 싶어 가끔은 ‘프롬프트 점성술 초기화’라 부르며 부가 요소를 싹 걷어내지만, 명세 문서 없이는 작업하기 어려움.

나도 비슷한 도구를 만들고 있는데, spekk-cli를 보니 비슷한 역할 구분에 도달한 점이 흥미로움. 이런 시스템 몇 개를 서로 비교해 보면 재미있을 것 같음.

이런 프레임워크에 대한 평가가 갈리고, 선호하는 SDD 프레임워크 위에 자체 작업 흐름 관리 기능을 만드는 경우가 적지 않다는 점이 흥미로움. 나도 기존 도구의 빈틈을 메우려고 별도로 만들었으며, SDD에는 Superpowers나 Matt Pocock의 스킬을 선호함.
우선 산출물의 노후화와 변경 이력 추적이 어려움. ADR이나 저장소 전체의 공통 패턴을 정해도, 나중에 결정을 바꾸거나 어기는 과정이 제대로 기록되는 일은 드묾. 검토도 같은 모델만으로는 부족해서, API 대신 기존 구독을 활용하며 여러 모델이 서로 검토하게 하고 싶었음.
검토·검증 중 원래 명세에 없던 기능이 필요해질 때도 있는데, 추가할지 미룰지에 대한 결정을 모두 추적하고 언젠가는 사람이 판단해야 함. 내가 선호하는 개발 절차에는 수동 승인 전 에이전트의 명세 검토, 코드베이스·기능 규모·보류 규칙에 따른 검토 반복도 들어감.
10줄짜리 변경에 100줄 넘는 명세를 만드는 식의 과도한 절차를 피하려고, 전체 절차가 필요한 작업과 기본 계획 기능만 쓰면 되는 빠른 작업을 구분하는 흐름도 만들었음. 다음 코드를 포크해 내 작업 방식에 맞게 추가했고, 꽤 잘 작동함. https://github.com/nutthouse/tutti.

LLM의 컨텍스트 크기가 100배 수준으로 늘기 전까지는, 명세 주도 작업 흐름에 크게 의존하지 않고 본격적인 에이전트 프로그래밍을 하기는 어려워 보임.
SDD라는 말은 포괄하는 접근법이 너무 다양해서 그 자체로는 별 의미가 없음. SpecKit과 SpecDD는 둘 다 강력하지만 겹치는 부분은 적음. SpecDD는 경계를 중심으로 시스템 구성요소를 기술하고, SpecKit은 명세를 변경하는 상당히 발전된 절차를 제공함.

링크를 열자마자 수많은 파일을 생성하는 모습이 보임. 늘 걸리는 부분은 그 많은 파일을 어떻게 검토하느냐임. 요구사항 프롬프트 하나를 여러 명세 파일로 늘리는 게 목적인지, 그 명세가 요구사항을 제대로 반영하는지는 어떻게 확인하는지 궁금함. 이런 프로젝트를 보고 나면 오히려 더 혼란스러워짐.

한동안 써봤는데, 코드는 더 이상 보지 않고 명세·계획·설계 문서만 보게 되는 것도 시간문제라고 봄. 일반 문서 뷰어나 편집기로는 문서 구성이 마음에 들지 않아 OpenSpec 전용 도구를 만들었음. 유용하게 쓰이길 바람. https://specks.nicotejera.com.

강하게 반대함. 나도 예전에는 그렇게 생각했지만, 앞으로는 명세를 직접 보는 대신 LLM이 코드를 읽어 실시간으로 명세를 생성하게 될 거라고 점점 확신하게 됨. 코드와 괴리를 만드는 것은 모두 위험 요인이자 유지보수 부담임. 현실을 반영하지 않는 명세가 무슨 소용인지 모르겠음. 실제를 반영하는 것은 코드임.

회사에서 OpenSpec을 도입했는데 정말 마음에 들지 않음. 중간 규모 이상의 변경마다 검토해야 할 마크다운 문서가 잔뜩 생김. 사람이 직접 쓴 문서는 없고, 모두 AI 특유의 문체가 가득한 저품질 생성물이라 개인적으로 거슬림. 이런 대형 명세보다 사람이 직접 쓴 짧은 명세가 훨씬 효과적임.
에이전트와 명세를 다듬고 구현한 뒤, 최종적으로 저장소의 모든 동작을 기술하는 ‘명세 모음’에 합친다는 구상이지만, 산문으로 코드의 모든 동작을 열거할 수는 없고 그럴 필요도 없음. 명세는 거의 즉시 낡아버림.

우리 회사도 OpenSpec을 도입했는데 작업 흐름이 크게 퇴보함. 모든 변경이 훨씬 번거로워짐.

에이전트 작업 흐름에 이런 구조를 강제하면 일은 늘고 품질은 떨어짐. 통제하고 있다는 착각에 가까움.

명세 작성에 고민과 노력을 들이지 않으면 읽기 어려운 저품질 문서가 될 수 있음. 실제로 명세의 완성도는 편차가 큼. 명세의 품질과 가독성은 여전히 사람이 크게 책임져야 하지만, 이 과정을 개선하기 위해 우리도 할 수 있는 일이 있음. 머지않아 훨씬 간결하고 반복적으로 다듬기 쉬운 방식으로 개선할 예정임.
피드백을 환영하며 직접 대화하는 것도 좋음. tabish@openspec.dev로 연락하면 일정을 잡을 수 있음.