Claude Code로 Documentation-Driven Development 워크플로우 구축 방법

Source: Dev.to

GitHub:
Docs:

문제점

대부분의 팀에서:

• PM이 요구사항을 어디엔가에 작성한다 (Notion, Jira, Google Docs)
• 개발자가 이를 읽고, 가정을 하며, 무언가를 만든다
• QA는 무엇을 기준으로 테스트할까?
• 버그가 보고되고, 책임이 전가된다

문서가 현실과 괴리된다. 이제는 무엇이 정확한지 아무도 모른다.

해결책: Docs as Code

스펙 파일이 진실의 원천이 되고, AI가 이를 직접 읽는다면?

PM/BA: /write-spec user-export     → docs/user-export/spec.md 생성
Dev:   /develop-feature user-export → Claude가 스펙을 읽고 기능을 구현

그게 전부다. 전화 게임이 없다. Claude는 PM이 작성한 동일한 스펙을 읽는다.

작동 방식

• PM이 /write-spec 실행 – Claude가 질문을 하고, 구조화된 스펙을 생성한다.
• Dev가 /develop-feature 실행 – Claude가 스펙을 읽고 전체 컨텍스트로 기능을 만든다.
• GitHub Actions가 알림 – 스펙이 변경될 때 팀 전체가 동기화된다.

왕복이 없다. “X가 무슨 뜻이었나요?” 같은 질문도 없다.

30초 만에 시작하기

npx create-ai-team

이 명령은 다음을 생성한다:

• .claude/commands/ – 워크플로우 명령들
• docs/example-feature/spec.md – 따라 할 수 있는 템플릿
• .github/workflows/ – 선택적 자동화

명령어들

왜 효과가 있는가

• 단일 진실 원천 – 스펙 파일이 정식 문서다.
• AI가 컨텍스트를 읽음 – 요구사항을 프롬프트에 복사‑붙여넣기 하지 않는다.
• 구조화된 포맷 – Mermaid 다이어그램, 오류 코드, 테스트 케이스 등.
• 버전 관리 – 스펙이 Git에 존재하고, 변경 이력이 추적된다.

오픈 소스

전체 프로젝트는 오픈 소스다:

• Repo:
• Docs:
• NPM: npx create-ai-team

사용해 보기

요구사항이 번역 과정에서 사라지는 것이 지긋지긋하다면, 한 번 시도해 보라:

npx create-ai-team

그런 다음 /write-spec my-feature를 실행하고 AI가 전체 컨텍스트를 이해하는 느낌을 확인해 보라.

현재 스펙과 코드를 동기화하기 위해 어떤 워크플로우를 사용하고 있나요? 다른 팀들의 방법도 듣고 싶습니다.