.png)
스펙 주도 AI 코딩, 실무 프레임워크 구축 가이드
기획연재 3편 : 전용 도구의 종속에서 벗어나, 마크다운(.md)과 폴더 규칙으로 유연한 AI 협업 환경 구축하기
📚 연재 안내 | 이 글은 3부작 연재의 마지막 3편입니다.
① 왜 개발자의 역할이 바뀌는가
② 바이브 코딩을 넘어 어떻게 일할 것인가
③ 팀에서 어떻게 운영할 것인가(현재 글)
지난 1, 2편을 통해 AI 코딩 시대에 개발자의 역할이 ‘시스템의 맥락을 설계하고 제약을 관리하는 오케스트레이터’로 이동하고 있음을 살펴보았습니다. 특히 대화형 코딩의 한계를 넘어 명세화(Specify) → 위임(Delegate) → 검증(Verify)으로 이어지는 작업 루프의 중요성을 강조했습니다.
최근 업계에서도 이러한 흐름을 돕기 위한 다양한 방법론과 도구들이 등장하고 있습니다. GitHub Spec Kit은 Spec → Plan → Tasks → Implement로 이어지는 파이프라인을 제안하고 있으며, Kiro와 같은 프레임워크는 요구사항과 설계를 전용 매니페스트 파일이나 CLI를 통해 관리하는 방식을 제공합니다. 또한 프롬프트-에이전트-스킬(Prompt-Agent-Skill) 아키텍처를 도입해 사내 표준을 강제하려는 시도도 활발합니다.
이러한 전용 도구들은 훌륭한 생산성을 제공하지만, 때로는 특정 벤더나 IDE 플러그인에 개발 프로세스가 강하게 종속(Lock-in)되는 결과를 낳기도 합니다. 도구가 변경되거나 서비스가 종료되면 그간 쌓아온 팀의 작업 프로세스와 시스템의 맥락(기억)이 함께 유실될 위험이 존재합니다.
따라서 이번 글에서는 특정 도구에 묶이지 않고, 오직 평범한 마크다운(.md) 파일과 디렉토리 규칙, 그리고 간단한 쉘 스크립트만으로 실제 프로덕션 환경에서 AI와 협업하는 프레임워크 구축 방안을 공유하고자 합니다.
1. 작업 공간의 통합: API와 UI를 하나의 컨텍스트로 묶기
AI 에이전트에게 기능을 위임할 때 종종 발생하는 문제 중 하나는, 백엔드 API 스키마는 변경되었는데 프론트엔드의 호출 코드가 누락되어 데이터 계약(Contract)이 어긋나는 현상입니다.
이를 방지하기 위해 저희 팀은 하나의 프로젝트 작업 공간(Workspace) 안에 연관된 Git 저장소(백엔드, 프론트엔드 등)를 형제 디렉토리로 배치하는 방식을 활용합니다.
[프로젝트 작업 공간]
├─ backend-api/ (제품 API 서버 저장소)
├─ frontend-admin/ (관리자 포털 웹 저장소)
└─ mobile-app/ (사용자 모바일 앱 저장소)
이 구조의 장점은 AI가 한 작업 공간 안에서 관련 저장소를 함께 탐색하고, 계층 간의 데이터 계약(Contract)을 맞춰보며 일관되게 수정할 수 있다는 점입니다. 스펙 문서에 *"새로운 노드 타입을 추가하고 API로 노출한 뒤, 관리자 목록 화면의 커스텀 훅에 배선하라"*고 명시하면, AI는 이 작업 공간 안에서 관련된 심볼과 의존성을 종합적으로 파악하여 풀스택(Full-stack) 단위의 변경 사항을 만들어 낼 수 있습니다. 다만 대형 저장소에서는 전체 코드가 한 번에 메모리에 올라가는 것이 아니라, 같은 작업 공간 안에서 필요한 파일을 탐색해 참조하는 방식에 가깝습니다. 컨텍스트는 작업 중 자동으로 채워지고 오래된 지시가 유실될 수 있으므로, 반드시 지켜야 할 지속 규칙은 CLAUDE.md 같은 파일에 명시해 두는 것이 안전합니다.
2. 3계층 지침 문서: 컨텍스트 관리와 '점진적 공개'
프로젝트의 모든 코딩 컨벤션과 설계 원칙을 하나의 README.md나 시스템 프롬프트에 담는 것은 AI 모델의 컨텍스트 윈도우를 낭비하고 정보 회상 능력을 떨어뜨리는 원인이 됩니다.
효율적인 컨텍스트 관리를 위해, 지침 문서를 프로젝트 최상단 → 저장소별 → 세부 규칙이라는 3계층으로 나누어 관리하는 것을 권장합니다.
[1계층] 프로젝트 지침 (CLAUDE.md / AGENTS.md):
작업 공간 최상단에 위치하는 '지도(Map)'입니다. 저장소 간의 관계나 "수정 후 필수 리뷰 프로세스" 같은 전역 규칙만 간략히 명시하고, 세부 문서는 링크로 연결합니다.
[2계층] 저장소별 지침 (backend/CLAUDE.md 등):
각 저장소의 '멘탈 모델'을 제공합니다. (예: "이 백엔드는 스키마 주도 아키텍처이며, 알림 기능 관련 규칙은 docs/notification.md를 참조할 것.")
[3계층] 세부 규칙 (docs/*.md):
특정 기능이나 도메인에 대한 '구속력 있는 계약'입니다.
이러한 '점진적 공개(Progressive Disclosure)' 구조를 취하면, AI가 특정 기능을 작업할 때 수백 페이지의 전역 규칙을 읽는 대신 관련된 세부 규칙 문서 하나만 추가로 로드하게 됩니다.
특히 세부 규칙 문서에는 *"스키마 JSON을 고치면 featureData.json의 버전을 상향할 것"*처럼, AI가 보편적인 지식만으로는 추론하기 어려운 시스템 고유의 제약 사항을 명시하여 예기치 않은 부작용을 예방할 수 있습니다.
3계층 지침 문서 아키텍처
3. 스펙 문서화 체계: -plan.md, -spec.md, -guide.md
기능 개발을 시작할 때 대화형 프롬프트에 의존하는 대신, 기능별 폴더를 생성하고 목적에 맞는 마크다운 문서를 작성하여 작업의 단위를 구조화합니다. 문서의 라이프사이클을 고려하여 주로 -plan.md, -spec.md, -guide.md 형태의 체계를 사용합니다. 팀에 따라 이 문서들을 requirements/design/tasks라고 부를 수도 있고, plan/spec/guide라고 부를 수도 있습니다. 핵심은 이름이 아니라 요구·설계·작업·현행화의 책임을 분리하는 데 있습니다.
1. *-plan.md (기획 및 요구사항):
해당 기능의 목표, 도메인 용어집, 그리고 상위 수준의 요구사항을 담습니다. 검증 가능한 인수 조건(Acceptance Criteria)을 작성하여 작업의 방향성을 맞춥니다.
2. *-spec.md (설계 및 작업 명세):
아키텍처 흐름, 데이터 모델, 그리고 구체적인 태스크 체크리스트를 포함합니다. 태스크는 파일 단위의 구체적 수정 사항으로 나누며, 문서의 마지막에는 컴파일 및 정적 분석(Lint) 실행 등 객관적인 검증 명령어를 포함하여 완료의 기준을 명시합니다.
3. *-guide.md (운영 가이드 및 현행화):
기능 구현이 완료된 후, 현재 시스템이 어떻게 동작하고 있는지(As-built)를 기록하는 문서입니다.
이러한 문서 분할의 핵심은 AI가 스스로 해야 할 일의 범위를 명확히 인지하게 하고, 검증 단계를 건너뛰지 않도록 마크다운 파일 자체에 프로세스를 내재화하는 데 있습니다.
스펙 주도 마크다운 워크플로우
4. 교차 AI 리뷰와 Fail-Closed 검증
AI가 생성한 코드의 품질을 AI 자신의 보고에만 의존하는 것은 시스템 안정성에 위험 요소가 될 수 있습니다. 객관적인 검증을 위해 다음과 같은 자동화된 리뷰 환경을 구성하는 것이 효과적입니다.
작업자와 리뷰어의 분리 (교차 리뷰):
코드를 작성한 AI 에이전트(예: Claude)가 스스로 리뷰를 수행하지 못하도록 합니다. 리뷰 스크립트는 완전히 독립된 컨텍스트를 가진 다른 에이전트(예: Codex)를 호출하도록 구성하여, 작업 중 발생한 논리적 맹점이 리뷰 단계로 전이되는 것을 방지합니다.
읽기 전용 (Read-Only) 제한:
리뷰를 담당하는 AI 에이전트에게는 코드 수정 권한을 부여하지 않고, 오직 스펙 문서와 구현된 코드 간의 정합성만 평가하도록 제한합니다.
구조화된 출력과 Fail-Closed 로직:
리뷰 결과는 자유로운 텍스트가 아닌 사전에 정의된 JSON 스키마 포맷으로 반환하도록 강제합니다. 만약 리뷰 AI가 JSON 형식을 지키지 않거나 필수 검증 필드를 누락한 경우, 이를 정상 동작으로 간주하지 않고 오류(Error)로 처리하여 프로세스를 중단시킵니다. 이러한 Fail-Closed 설계는 검증 파이프라인의 신뢰도를 높여줍니다.
5. 문서 라운드트립: 문서와 코드의 지속적 동기화
코딩 속도가 빨라질수록 설계 문서와 실제 코드 간의 괴리가 발생할 확률도 높아집니다. 이를 방지하기 위해 문서의 작성과 현행화를 닫힌 루프(Closed Loop) 형태로 운영하는 것이 중요합니다.
1. 기능 개발 시 *-plan.md와 *-spec.md를 기반으로 구현을 진행합니다.
2. 코드가 반영되고 나면, 작업의 마지막 단계로 해당 코드의 실제 구현 내용을 바탕으로 관련 문서들을 모두 업데이트하도록 지시합니다.
3. 이때 현재 상태를 기록하는 *-guide.md를 생성할 뿐만 아니라, 기존의 *-spec.md와 *-plan.md 역시 구현 과정에서 발생한 설계 변경 사항이나 추가된 예외 케이스를 반영하여 철저하게 현행화합니다.
이렇게 세 가지 문서 모두를 최신 상태로 동기화(Round-trip)해 두면, 향후 해당 기능에 대한 버그 수정이나 2차 고도화 작업이 필요할 때, 낡은 과거의 문서가 아닌 현행화된 이 *-plan.md 및 *-spec.md 파일로부터 안정적으로 새로운 태스크를 파생(Derive)시켜 사이클을 재시작할 수 있습니다. 단일 진실 원천(SSOT)인 코드와 문서가 함께 유기적으로 진화하는 체계가 만들어지는 것입니다. 이 ‘문서 라운드트립’이야말로 특정 도구에 기대지 않고도 문서가 코드와 함께 낡지 않게 만드는, 이 프레임워크의 핵심 차별점입니다.
문서와 코드의 라운드트립 순환
마치며: 유연하고 지속 가능한 AI 협업 환경
지금까지 살펴본 프레임워크와 실무 환경 구축 방안은 복잡한 전용 솔루션 없이도 충분히 구현 가능합니다. 텍스트 기반의 마크다운과 일관된 폴더 규칙으로 구성된 환경은 도구의 변화에도 유연하게 대처할 수 있는 기반이 됩니다.
본문의 내용 외에도 실무 적용 시 고려해 볼 만한 몇 가지 원칙이 있습니다.
명확성의 관문 (Clarity Gate): 요구사항이 모호할 때는 AI가 임의로 코드를 생성하지 않도록 제한하고, 개발자에게 먼저 질의하여 스펙을 구체화하도록 지침을 설계해 보세요.
모범 사례 참조 유도: 코딩 컨벤션을 텍스트로 길게 설명하는 대신, 잘 짜인 '샘플 디렉토리'나 기존 컴포넌트를 명시적으로 참조하게 하면 일관성 있는 결과를 얻기 유리합니다.
팀 단위로 확장할 때 중요한 것은 도구보다 먼저 ‘규칙’입니다.
여기서 한 걸음 더 나아가 팀 전체의 DevOps 흐름으로 확장하려면, 새로운 AI 코딩 도구나 자동화 솔루션을 도입하는 것만으로는 충분하지 않습니다. 먼저 각 팀이 지금 어떤 방식으로 이슈를 정의하고, 어떤 기준으로 리뷰하며, 어떤 테스트와 배포 절차를 거쳐 운영 문제를 다시 개발 과제로 되돌리는지를 들여다보아야 합니다.
작은 지침 파일과 명세 문서부터 시작하는 일은 어느 팀이든 오늘 바로 할 수 있습니다. 다만 이를 팀 단위로 확산할 때는 현재 프로세스를 한 번 진단하고 구조화하는 과정이 도움이 됩니다. 중요한 것은 특정 벤더나 솔루션에 종속되는 것이 아니라, 각 팀의 코드베이스·저장소 구조·리뷰 문화·테스트 성숙도·배포 정책에 맞는 ‘명세 → 위임 → 검증’ 규칙을 먼저 세우는 일입니다.
AI DevOps는 이 관점을 제품 구조에 반영한 운영 환경입니다. 모호한 이슈는 명확도 게이트가 입구에서 거르고, 불완전한 기능은 AI 자동 테스트가 출구에서 걸러내며, 실패한 테스트는 다시 추적 가능한 버그 이슈로 되돌아갑니다. AI DevOps는 규칙을 대신 만들어 주는 제품이 아니라, 각 팀이 합의한 규칙이 이슈·코드·테스트·배포·운영 로그를 따라 끊기지 않고 실제 운영 루프로 작동하게 돕는 실행 환경입니다.
특정 벤더의 도구는 시간이 지나면 유행이 바뀌거나 사라질 수 있습니다. 하지만 순수한 텍스트 기반의 문서 구조와 체계적인 리뷰 프로세스로 쌓아 올린 시스템의 '기억'은 향후 어떤 최신 AI 모델을 도입하더라도 변함없는 가치를 지닐 것입니다.
프로젝트 최상단에 간단한 지침 파일을 만들고, 기능 단위의 명세 문서를 폴더로 관리해 보는 것부터 시작해 보시길 권장합니다. 이러한 작은 체계의 도입이 다가오는 AI 개발 시대에 프로젝트를 안정적으로 유지하는 초석이 될 것입니다.
