사양 문서는 코드의 대체재가 될 수 있을까? 에이전트 코딩의 현실적인 문제점

게시글은 에이전트 코딩(Agentic Coding)에서 사양 문서가 코드보다 단순하다는 오해를 지적하며, OpenAI의 Symphony 프로젝트를 예시로 들었다. Symphony 프로젝트의 사양 문서(SPEC.md)는 데이터베이스 스키마, 동시성 제어, 재시도 로직 등 코드와 유사한 내용을 포함하고 있다. 기술적으로 보면, 사양 문서가 실제 코드와 구별하기 어려울 정도로 상세해지면서, 사양 문서가 코드의 대체재가 될 수 없음을 보여준다. 특히, Dijkstra의 '좁은 인터페이스(Narrow Interfaces)' 개념을 인용하여, 엔지니어링 작업에서 코드와 사양 문서 간의 경계가 모호해짐을 강조한다.

게시글은 AI를 활용한 코드 생성의 신뢰성 문제를 지적하며, Symphony 프로젝트의 Haskell 코드 생성 실패 사례를 제시한다. 저자는 Claude Code에게 Symphony를 Haskell로 구현하도록 요청했지만, 여러 버그가 발생했고, 심지어 '작동'하는 경우에도 코드 생성에 실패했다. 실제 사례로는, YAML 사양의 광범위한 사용에도 불구하고, 많은 구현체가 사양을 완전히 준수하지 못하는 점을 언급하며, AI 환각(Hallucination)과 같은 문제로 인해 사양 기반 코드 생성의 신뢰성이 떨어진다는 점을 강조한다.

게시글은 사양 작업이 코딩 작업보다 더 사려 깊어야 한다는 오해를 비판하며, 현재 엔지니어링 환경에서 사양 문서의 품질 저하 가능성을 지적한다. 특히, 기술적으로 보면, Symphony 사양 문서가 일관성, 목적, 또는 전체적인 그림에 대한 이해가 부족한 'AI-written slop'으로 묘사된다. 또한, GDPR 규제 준수(GDPR Compliance)와 같이, 사양 문서 작성 시 고려해야 할 사항들이 많아지면서, 사양 문서의 품질 유지가 더욱 어려워지고 있다. 따라서, 사양 문서가 시간 절약 도구가 될 수 없으며, 명확성과 세부 사항이 부족한 문서를 입력하면, AI가 이를 보완하여 신뢰할 수 있는 코드를 생성할 수 없다는 점을 강조한다.

댓글에서는 사양 문서의 복잡성에 대한 공감대가 형성되었다. 한 사용자는 10개 이상의 파일과 100~200줄의 변경 사항이 있는 MR을 검토한 경험을 공유하며, 실제 코드 변경은 1줄에 불과했지만, 나머지 대부분은 사양이었다고 언급했다. 특히, Renovate 중앙 레포지토리에서 의존성 관리를 위해 사용되는 사양 문서가 불필요한 내용으로 가득 차 있었다고 지적했다. 또 다른 사용자는 클라이언트로부터 상세한 사양을 얻는 것이 가장 어려운 작업이라고 언급하며, 사양 문서의 중요성을 강조했다.