1. 시작하며

2. SDD 도입 당초의 개발 워크플로우

3. Issue 문서를 쌓아가는 것의 고충

4. 고충을 줄이기 위해 사양 파일을 남기는 방식을 바꿨다

5. 무엇을 프로덕트 문서(Product Document)로 옮기고, 무엇을 Issue 문서(Issue Document)에 남길 것인가

6. 이 운영 방식으로 바꾸고 무엇이 좋아졌는가

7. 마치며

안녕하세요, AgVenture Lab의 Yamada입니다.

이 기사에서는 사양 주도 개발(이하 SDD)을 도입한 후, Issue마다 만들던 사양 파일을 남기는 방식을 재검토한 이야기를 쓰겠습니다.

먼저, 이 이야기의 전제로서 저희 팀의 개발 진행 방식을 간단히 설명하겠습니다.

저희 팀은 애자일 개발(Agile Development) 안에서 Issue 단위로 기능 추가나 개선을 진행하고 있습니다.

설계 정리, 구현 계획, 구현 보조 단계에서는 AI에게 사양 파일이나 기존 코드를 전달하며 개발하고 있습니다.

여기서 말하는 SDD는 구현 전에 해당 Issue의 요구사항, 설계와의 대응 관계, 구현 계획을 문서화하고, 그것을 바탕으로 개발을 진행하는 방식입니다.

도입 목적은 구현 전에 생각을 정리하는 것과 AI에게 전달할 전제를 명확히 하는 것이었습니다.

SDD를 도입한 직후에는 Issue마다 필요한 정보를 정리할 수 있어서 상당히 진행하기 편하다고 느꼈습니다.

하지만 Issue 문서가 늘어남에 따라 다음과 같은 고민이 생겨났습니다.

주요 고민

• 사양 파일이 늘어나면 지금도 유효한 전제를 찾기 어려움
• 오래된 사양 문서가 AI에게 전달하는 문맥(Context)의 노이즈가 됨
• 일시적인 검토 메모와 길게 남겨두어야 할 사양이 섞임

사람이 읽을 때도, AI에게 문맥으로 전달할 때도 현재의 판단에 불필요한 정보가 섞이기 쉬워졌습니다.

그래서 Issue 문서를 '작업 중인 판단이나 검토를 두는 곳', 프로덕트 문서를 '앞으로도 참조하고 싶은 전제를 남기는 곳'으로 나누기로 했습니다.

참고로, 본 기사에서는 특정 도구의 비교는 하지 않습니다.

저희는 Codex와 독자적으로 작성한 스킬을 사용하고 있지만, 이 기사에서는 도구의 차이가 아니라 'Issue별 문서를 어떻게 남길 것인가'에 초점을 맞추어 이야기하겠습니다.

먼저, SDD를 도입하기 시작했을 무렵의 개발 워크플로우입니다.

이 흐름에서는 Issue마다 다음과 같은 파일을 만들었습니다.

spec.md : 해당 Issue에서 실현하고자 하는 요구사항을 정리한다

design_mapping.md : 요구사항과 기존 설계·기존 코드의 대응 관계를 정리한다

plan.md : 구현 방침이나 작업 순서를 정리한다

tasks.md : 구현 시 진행할 작업을 세부적으로 나눈다

기능 추가를 계속하면 디렉토리 구성은 다음과 같이 됩니다.

├── specs
│ ├── 20260101101112_add-xx-feature
│ │ ├── spec.md
...

본 기사에서는 specs/xxx/ 하위에 만들어지는 이 파일 세트를 Issue 문서라고 부릅니다.

이렇게 Issue마다 파일을 나누는 것 자체는 작업 중에는 편리했습니다.

요구사항, 설계와의 대응 관계, 구현 계획을 나누어 정리할 수 있기 때문에 Issue 단위로 개발을 진행하기 쉬워집니다.

AI에게 전달하는 정보도 Issue마다 모여 있기 때문에 구현 전의 정리나 구현 보조에도 사용하기 쉽습니다.

하지만 작업 중에 편리한 형태와 Issue가 끝난 후에도 다루기 쉬운 형태는 달랐습니다.

기능 추가를 거듭하면서 Issue 문서는 조금씩 다루기 어려워졌습니다.

다루기 어려워진 이유는 성격이 다른 정보가 같은 장소에 계속 남았기 때문입니다.

예를 들어, 구현 후에도 유효한 업무 규칙이나 화면 사양.

그 한편으로는 해당 Issue에서만 필요했던 비교 메모, 구현 시 고민했던 내용, 도중에 채택하지 않은 안.

이러한 정보들이 동일한 Issue 문서 안에 들어 있었습니다.

Issue를 진행하는 동안에는 그래도 문제가 되지 않습니다.

그 Issue 안에서 생각한 것을 한꺼번에 추적할 수 있기 때문입니다.

하지만 Issue가 끝난 후에도 같은 장소에 계속 남아 있으면, 나중에 볼 때마다 '이것은 지금도 유효한 사양인가' 아니면 '그 Issue 안에서만 끝난 검토 메모인가'를 구분해서 읽어야 하는 필요가 생깁니다.

AI에게 문맥으로 전달하는 경우도 마찬가지입니다.

오래된 검토 메모나 도중에 채택하지 않은 안이 섞이면, 그것들도 현재의 판단 재료에 포함되기 쉽습니다.

처음에는 Issue 문서의 수 자체가 늘어난 것이 문제라고 생각했습니다.

하지만 실제로 재검토해 보니 문제는 파일 수가 아니었습니다.

문제는 정보의 역할이 다른 것을 Issue 단위라는 동일한 묶음으로 계속 남겨두고 있었다는 점이었습니다.

Issue를 진행하기 위한 정보는 해당 Issue 안에서는 필요합니다.

하지만 Issue가 끝난 뒤에 현재의 사양(Specification)으로 취급하고 싶은 정보는 아닐 수도 있습니다.

그럼에도 불구하고 모든 것을 동일한 Issue 문서 안에 남겨두었기 때문에, 현재의 전제와 과거의 검토 경위가 뒤섞여 보이게 되었습니다.

이 부분이 Issue 문서를 쌓아 올리는 과정에서 가장 큰 과제였습니다.

과제가 보인다고 해서 사양을 쓰는 것 자체를 그만둔 것은 아닙니다.

재검토한 것은, Issue마다 만든 사양 파일을 Issue가 끝난 후에도 그대로 현재의 사양으로 계속 취급하는 방식이었습니다.

그래서 Issue 문서와 프로덕트 문서(Product Document)의 역할을 나누었습니다.

Issue 문서는 Issue를 앞으로 진행시키기 위한 작업 공간입니다.

요구를 정리하거나, 설계와의 대응 관계를 확인하거나, 구현 계획을 세우기 위해 사용합니다.

프로덕트 문서는 Issue가 끝난 후에도 계속 사용하는 지식의 저장소입니다.

용어 정의, 업무 규칙, 제약 사항, 비기능 요구사항(Non-functional requirements) 등 향후 개발에서도 참조하고 싶은 전제를 남깁니다.

크게 나누면, Issue 문서에는 "그 Issue를 진행하기 위한 정보"를 두고, 프로덕트 문서에는 "앞으로도 참조하고 싶은 정보"를 두는 방식입니다.

변경 후의 구성은 예를 들어 다음과 같은 형태입니다.

docs/product/
├── glossary.md
├── domain-rules.md
...

docs/product/에는 앞으로도 참조하고 싶은 전제나, Issue를 넘나들며 사용하는 사양을 둡니다.

작업 중인 Issue 문서는 specs/ 하위에 두고, Issue가 완료되면 specs/archive/로 옮깁니다.

여기서 중요한 것은 종료(Close)된 Issue 문서를 삭제하지 않는 것입니다.

과거의 검토 경위까지 지워버리면, 나중에 "왜 이런 판단을 했는가"를 추적할 수 없게 되기 때문입니다.

따라서 과거의 Issue 문서는 specs/archive/에 남겨둡니다.

다만, 평소 AI에게 전달하는 컨텍스트(Context)나 현재의 사양을 확인하는 장소에서는 제외합니다.

이로써 현재의 사양을 보는 장소와 과거의 검토 경위를 보는 장소를 분리할 수 있게 되었습니다.

운영을 바꿀 때 고민했던 점은 어떤 정보를 docs/product/로 옮길 것인가였습니다.

지금은 고민될 때 "다음 Issue에서도 전제로 참조하고 싶은가"를 기준으로 판단하고 있습니다.

다음 Issue에서도 참조하고 싶은 정보라면 docs/product/로 옮깁니다.

예를 들어 용어 정의, 업무 규칙, 권한 제약, 다른 기능에도 영향을 미치는 화면 사양, 비기능 요구사항이나 운용상의 제약 등이 있습니다.

반면, 해당 Issue 안에서만 필요했던 비교 메모, 도중에 채택하지 않은 안, 구현 시 고민했던 내용은 억지로 프로덕트 문서로 옮기지 않습니다.

그러한 정보는 Issue 완료 후에 specs/archive/에서 참조할 수 있으면 된다고 생각합니다.

모든 것을 깔끔하게 정리하려고 하면 운영이 무거워집니다.

따라서 처음부터 완벽을 목표로 하지 않고, "다음 Issue에서도 참조하고 싶은가"를 기준으로 남길 정보를 선택하도록 하고 있습니다.

가장 좋았던 점은 목적에 따라 참조처를 나눌 수 있게 된 것입니다.

이전에는 과거의 Issue 문서를 볼 때마다 "이것은 지금도 유효한 사양인가", "그 Issue만의 검토 메모인가"를 일일이 구분하며 읽어야 했습니다.

지금은 Issue를 넘나들며 참조하고 싶은 전제는 docs/product/를 보고,

과거의 판단 경위를 확인하고 싶을 때는 specs/archive/를 봅니다.

이렇게 구분해서 사용할 수 있게 되었습니다.

AI에게 전달할 컨텍스트도 선택하기 쉬워졌습니다.

종료된 Issue의 검토 메모를 통째로 전달하는 것이 아니라, 지금도 유효한 전제를 중심으로 전달할 수 있기 때문에 AI에게 불필요한 과거 정보를 읽히는 상황을 줄일 수 있었습니다.

특히 AI에게 "현재의 사양을 전제로 생각해달라"고 요청할 때, 어떤 파일을 전달해야 할지 판단하기 쉬워진 점이 큽니다.

이전에는 과거 Issue 중에서 지금도 유효한 정보를 찾아 전달해야 했습니다.

지금은 우선 docs/product/를 전달하고, 필요에 따라 specs/archive/에서 과거 경위를 보충하는 방식으로 구분해서 사용할 수 있습니다.

한편, Issue 완료 후에 앞으로도 남겨야 할 내용을 docs/product/에 반영하는 수고는 늘어났습니다.

무엇을 프로덕트 문서로 옮길지는 지금도 운영하면서 조정하고 있습니다.

그럼에도 불구하고, "현재의 사양"과 "그 당시의 검토 메모"를 동일한 비중으로 계속 나열해 두는 상태는 줄일 수 있었습니다.

사람이 읽을 때도, AI에게 문맥 (Context) 으로 전달할 때도, "먼저 무엇을 보아야 하는가"를 판단하기 쉬워진 것이 이 운영 방식으로 변경하며 얻은 가장 큰 효과였습니다.

SDD를 도입하며 느낀 점은, 사양을 작성하는 것뿐만 아니라 작성한 사양을 어떻게 남길 것인지까지 고민할 필요가 있다는 것이었습니다.

Issue 문서 (Issue document) 는 Issue를 진행하는 데 있어서는 편리합니다.

다만, Issue가 종료된 후에도 그대로 계속 쌓아두기만 하면, 현재의 전제 조건과 과거의 검토 경위가 섞이기 쉽습니다.

이번에는 Issue 문서와 프로덕트 문서 (Product document) 의 역할을 분리함으로써 이러한 상태를 재검토했습니다.

비슷한 운영을 시도해 보려 한다면, 처음부터 크게 바꿀 필요는 없다고 생각합니다.

우선 최근에 완료된 Issue 문서 하나를 검토하여, "다음 Issue에서도 전제로 참조하고 싶은 정보"만을 docs/product/로 옮겨 보는 것입니다.

그것만으로도 현재의 사양과 과거의 검토 경위를 분리하는 계기가 됩니다.

마찬가지로, SDD 도입 후의 사양 파일 운영으로 고민하고 계신 분들에게 참고가 된다면 기쁘겠습니다.

조금이라도 도움이 되었다면, '좋아요'나 '저장(Stock)'을 해주시면 큰 힘이 됩니다.