적당한 도구는 가짜 사양 주도 개발(Spec-Driven Development)로 만들어서 공개하자

이번에 pouch라는 CLI 도구를 공개했습니다.

@card

pouch는 Linux 계열 명령어에서 친숙한 touch, mkdir를 자동으로 판별하여 파일과 디렉터리를 구축해 줍니다. 예를 들어 src/tool/main.go라는 파일이 필요할 때, 다음과 같이 직관적인 생성이 가능합니다.

# Before: mkdir와 touch를 조합함
mkdir -p src/tool
touch src/tool/main.go
...

확장자를 지정하지 않으면 디렉터리로 취급됩니다. 여러 개의 경로와 파일을 동시에 지정하여 생성하는 것도 가능합니다. 요컨대 touch, mkdir -p를 적절히 통합하고 확장한 도구라고 할 수 있습니다. 이것이 pouch라는 이름의 유래이기도 합니다.

리포지토리(Repository)에서 공개 중인 데모 영상도 확인해 보세요. go install과 mise use를 지원하므로, 관심이 있다면 사용해 보시기 바랍니다.


솔직히 말해서 pouch는 쉘 스크립트(Shell Script)로도 간단히 만들 수 있습니다. 분명 .bashrc나 .zshrc에 비슷한 것을 작성해 두신 분들도 많지 않을까요?

그럼에도 불구하고 도구로서 공개하고 싶은 큰 이유는 유지보수성과 이식성에 있습니다. dotfiles 내에 직접 만든 명령어를 두는 것만으로도 충분할지도 모릅니다. 하지만 다음과 같은 문제들이 남습니다.

• 테스트 코드(Test Code)를 작성하기 어려워 품질이 저하되기 쉽다
• 버전 관리(Version Control)가 복잡해진다
• 누군가에게 배포하기 위해 특별한 준비가 필요하다
• 배포할 수 있다고 해도 동작을 보장할 수 없다

이러한 문제들은 별도의 리포지토리로 공개함으로써 말끔히 해결됩니다 (정확히는 해결할 수밖에 없습니다).

게다가 누군가가 보고 있는 것이니 제대로 작성해야지! 라는 마음이 생겨 자연스럽게 품질이 올라갑니다. 이것이 가장 큰 장점일지도 모릅니다.

이번 도구는 AI 에이전트(AI Agent)가 대부분을 만들었습니다. 기왕 하는 김에 사양 주도 개발(Spec-Driven Development, SDD)을 해볼까 생각했습니다만, 이 정도 규모의 CLI 도구라면 그렇게 거창한 것은 필요하지 않습니다. 그래서 조금 경량화된 형태로 커스터마이징한 결과, 필요 충분한 품질이 되었다고 느낍니다. 이 글에서는 그 과정을 소개하고자 합니다.

참고로, 이번 도구 제작에는 다음 글이 큰 도움이 되었습니다. 이번에는 Go 언어로 구현했지만, 특정 언어에 국한되지 않고 범용적으로 사용할 수 있는 내용이라고 생각합니다.

이 글에서는 사양 주도 개발(SDD)을 「사양(Specification)」을 중심으로 두고 개발을 진행하는 기법으로 파악합니다. 특히 AI 에이전트와 조합할 경우에는 먼저 사양서를 작성하고, 그에 따라 구현과 테스트를 진행하는 형태가 됩니다. 요컨대,

• 구체성이 높은 코드가 아니라, 보다 추상적인 결과물인 사양서를 중심에 둔다
• 코드를 수정했을 경우에도 반드시 사양서와 동기화하여 항상 신뢰할 수 있는 상태로 유지한다

라는 점이 핵심이라고 저는 생각합니다. 코드를 AI가 크게 진전시켜 준다면, 인간은 먼저 사양에 집중하고 설계나 검증의 관점을 그곳에 반영하는 것이 중요하다는 아이디어입니다.

사양 주도 개발의 프레임워크로는 spec-kit이 유명하지만, 이는 조금 무겁습니다. 이번에 만들고자 하는 것은 결국 작은 CLI 도구이기에, 거대한 애플리케이션조차 대응할 수 있는 프레임워크를 유용하는 것은 조금 망설여집니다.

사양서란 그 어감상 주로 외부 설계서를 가리킨다고 느낍니다. 주로 엔드 유저(End User) 입장에서 본 사양 말이죠. 하지만 「외부 설계서만 먼저 고정하고, 내부 설계는 구현 시점에 처음 생각한다」는 것은 분명히 부적절합니다. 설계는

What: 이용자나 업무에 대한 계약인 「무엇을 실현할 것인가」 -
How: 그 계약을 실현·유지할 수 있는지를 검증하는 「어떻게 실현할 것인가」

를 왕복하며 생각하는 것, 즉 외부 설계와 내부 설계는 표리일체입니다. 소박하게 생각하면, 사양 주도 개발에서 사전에 정교하게 다듬어야 할 문서는 외부 설계서와 내부 설계서의 쌍이라는 뜻이 됩니다.

그런데 리포지토리에는 일반적으로 README.md가 있습니다. AI를 이용하는 리포지토리에는 AGENTS.md나 CLAUDE.md 등 코딩 에이전트를 향한 지시 파일이 있습니다. 저는 이것들이 미니멈한 외부 설계서와 내부 설계서에 매우 가까운 성질을 가지고 있다고 생각했습니다. 즉,

• 외부 설계서로서
  README.md

를 정교화하고 - 내부 설계서로서
AGENTS.md

를 정교화한다

라는 방침으로 문서를 정리하면, 자연스럽게 사양 주도 개발 (Spec-Driven Development) 같은 방식으로 진행할 수 있지 않을까 생각했습니다.

물론,

• README.md는 상세한 외부 설계서가 아니라, 어디까지나 간결한 가이드이다
• AGENTS.md는 프로젝트 고유의 정보에 국한되지 않고, 개발자나 팀 단위의 규칙도 포함한다

와 같은 전제가 있지만, 정보의 성질로서는 상당히 겹치는 부분이 있지 않을까요. 이번에는 이 방침으로 진행해 보겠습니다.

AI에게는 전제 지식을 제대로 전달해 둡시다. AGENTS.md에 다음과 같은 내용을 기재해 둡니다.

외부 설계서에는 사용자 관점에서의 동작 사양을 기재합니다. 솔직히 말해서, 이 정도 규모의 도구라면 상세한 외부 설계서는 필요 없습니다. README.md에 외부 설계서적인 내용을 기재하고, 나머지는 설치 방법과 라이선스 정도만 적어두어도 충분합니다.

물론 사람이 읽는 것이므로, 사람에게 읽기 쉬운 문장이어야 합니다. 하지만 쓰는 사람인 인간이 읽기 쉬운 문장으로 정리해 나가는 과정이야말로, 사양서를 브러시업 (Brush-up) 하는 작업 그 자체라고 느낍니다. 이상한 사양이 없는지, 더 좋은 사양이 없는지를 고민하는 과정에서 자연스럽게 좋은 내용이 될 것입니다.1

내부 설계서에는 사용자가 신경 쓸 필요가 없는 정보, 즉 프로젝트 전체의 아키텍처 (Architecture)나 사상을 기재합니다. 이 부분은 개발자로서의 스킬이 상당히 시험받는 지점이지만, 이 또한 작은 도구라면 그렇게 공들여 만들 필요는 없습니다.

AI에게 코딩을 의뢰할 때, 예를 들어 Go 언어라면 "Go 언어의 CLI 도구로서 자연스러운 설계로 해줘"라고 말하면 충분히 동작하는 것을 만들어 줍니다. 그것을 참고하여 구현하면서 문서를 만들어도 문제없습니다. 중요한 것은 실제 코드를 문서로서 영속화하는 것입니다. 사양 주도 개발의 중심은 문서이므로, 코드만 앞서 나가지 않도록 주의를 기울입시다.

그리고 인간의 역할로서 중요해지는 것은, 생성물에서 위화감을 느끼는 것입니다.

• 왠지 클래스의 책임이 과도하지 않아?
• 이렇게 하면 테스트 용이성 (Testability)에 영향을 주지 않을까? 억지로 테스트하고 있는 거 아냐?

와 같은 위화감은 즉시 AI에게 전달합시다. 그 지적이 맞았을 경우, 과거에 잘못된 방향으로 진행해 버렸던 사실도 문서에 써 두면 더욱 좋습니다.

그나저나 README.md는 일반적으로 영어입니다…. 슬프게도 영어가 서툰 저는 README.md의 일본어판인 README-ja.md를 만들어 동기화하도록 했습니다. 이렇게 하면 일본어판을 편집해도 AI에게 영어판으로의 반영을 의뢰할 수 있습니다.

구체적으로는 AGENTS-ja.md에 다음 내용을 기재합니다. 물론 일본어판에도 마찬가지입니다.

또한, 이러한 작업은 반복해서 사용하는 것이라고 느껴져서 스킬 (Skill)화 했습니다.

apm에서 설치할 수 있도록 해두었으니, 괜찮으시다면 사용해 보세요.

apm install zawa-kyo/skills/dev/bootstrap-repo-docs

README.md는 세상에 공개하는 것이므로, 조금이라도 자연스러운 영어로 해두고 싶습니다. 하지만 저는 자연스러운지 어떤지 알지 못합니다. 그래서 영어 문서 리뷰에는 stop-slop을 사용하고 있습니다.

@card

정말로 자연스러워졌는지는 모르겠지만, 아마 좋아졌을 것입니다. 아마도.

이상, 가짜 사양 주도 개발로 적당한 도구를 만들어 공개해 본 과정의 소개였습니다. "공개해 보았다"는 부분에 새로움은 없으므로, CI 설정 등은 리포지토리 (Repository)를 참조해 주세요. 아래는 내용 요약입니다.

• pouch라는 작은 CLI 도구를 사양 주도 개발처럼 만들어 보았다 - 사양 주도 개발을 작게 파악하면, 다음 문서에서도 사양서의 책임을 맡을 수 있다
• 외부 설계서로서의 README.md
• 내부 설계서로서의 AGENTS.md나 CLAUDE.md
• 외부 설계서로서의 역할
• 인간이 위화감을 느끼는 것이 중요하다. 그것도 문서에 반영한다
• 영어가 서툰 사람은 일본어판을 만들어 AI에게 동기화하도록 하자

AI의 발전으로 편리해진 반면, 코딩이 지루해졌다는 말을 자주 듣습니다. 그 마음은 충분히 이해합니다. 그 반발 때문인지, 이 글은 인간 100%로 쓰기로 결정했습니다.

이번 도구 제작은 "가끔은 코드를 직접 짜고 싶다"라는 마음에서 시작되었습니다. AI에게 써달라고만 하니, 결국 리뷰만 하게 됩니다. 하지만 역시 무언가를 만드는 것은 즐겁습니다. 코드와 관계를 맺는 방식은 변하더라도, 변하지 않는 것도 있는 법이니까요.

"CLI 도구로서 부자연스러운 사양이 있다면 알려줘"라고 AI에게 말하면 아주 많이 알려줍니다. 일반적인 지식량으로는 인간이 AI를 이길 수 없으므로, 마음껏 물어봅시다. 인간은 도메인 지식 (Domain Knowledge)으로 활약하면 되는 것입니다. ↩