2025.12.10 사내 발표 - 들쭉날쭉한 AI 품질, 팀 SSOT 문서로 해결하기

최근 '팀 차원에서 시스템적으로 AI 품질을 어떻게 올릴 수 있을까?'에 대한 고민과 해결 방법에 대해 사내 발표를 했다. 되도록 개인의 역량에 의존하지 않고, 팀 차원에서 AI를 활용하여 시스템적으로 안정적으로 서비스를 운영할 수 있는 방법론에 대해 소개한다.

---

개발팀의 고민: AI 품질 문제

AI를 활용한 개발에서 가장 중요한 것은 '속도'가 아니라 '정확한 방향'입니다.

AI의 구조적 한계

1. 프롬프트 의존성
   개발자는 작업을 시작하기 전, 스스로 과거의 히스토리를 파악하고 도메인 정책을 검토합니다.
   반면, AI는 사용자가 입력한 프롬프트와 연관된 코드만 읽습니다. 스스로 과거 작업이나 도메인 지식을 찾지 못하고, 오로지 입력된 프롬프트에만 의존합니다.
2. 불확실한 요구사항(Gray Zone)의 임의 추론
   명확하지 않은 요구사항은 가장 그럴듯한 로직으로 채워 넣기 때문에, 의도와 다른 구현이 반영될 가능성이 높습니다.

✅ 충분한 맥락을 제공한 경우

"구좌 신청 임시저장 API를 만들어줘. 임시저장은 제출하기 전에 사용자가 데이터를 보관하는 용도로 사용하는 것이야. 그래서 입력한 값에 대해서만 최소한의 Validation을 통과하면 DRAFT 상태로 저장해. 검증이 필요한 항목은 다음과 같이..."

→ 의도한 구현

❌ 컨텍스트가 부족한 경우

"구좌 신청 임시저장 API 만들어줘."

→ AI가 Gray 영역을 스스로 추론하여 개발하므로, 일관성이 없거나 도메인 정책 위반됨

이는 아래와 같은 문제를 야기합니다. 이것은 개인이 아닌 팀 전체의 비용입니다.

개인이 아닌 팀 전체의 비용

AI와 일을 잘 하려면?

위 비용을 개인의 문제가 아니라 팀의 부채로 보고, 팀 차원에서 어떻게 하면 의도한 대로 AI를 일 시킬 수 있을까 고민하게 되었습니다.
이 글에서는 두 가지 측면에서 해결 방법을 각각 제안합니다.

1. 프롬프트 엔지니어링 : AI에게 어떻게 물어볼 것인가
2. 충분한 컨텍스트 : AI에게 무엇을 알려줄 것인가

---

Step 1. 명세를 통한 정확한 구현 (SDD)

SDD 란?

SDD(Spec-Driven Development)는 코드를 작성하기 전에 먼저 명세(Specification)를 작성하고, 이를 기반으로 개발을 진행하는 방식입니다. AI에게 "무엇을 만들어야 하는지"를 명확하게 전달한다면 의도한 결과물을 얻을 수 있을 것입니다.

SDD 개발 방법론으로 구현하는 과정을 살펴보겠습니다.

프롬프트 엔지니어링은 SDD 도구가 책임진다

SDD 도구(spec-kit, task-master-ai 등)가 개발자가 구현을 위해 수행하던 프로세스들을 추상화하여 구조화된 명령어 로 제공합니다.

아래 더보기를 통해 spec-kit 기준으로 명령어별 어떤 개발 프로세스를 추상화했는지 간략히 소개합니다.

spec-kit에서 제공하는 /specify, /plan, /tasks 명령어 통해 명세와 Task 단위의 TODO List가 작성됩니다.
명령어는 주기적으로 추가되고 내용이 조금씩 변경되고 있어서 간략한 설명 위주로 안내드립니다.

1. /speckit.specify - 명세 작성

• 브랜치 자동 생성 (5-feature-name)
• WHAT(무엇) + WHY(왜) 집중 - 기술 용어 금지
• 최대 3개 [NEEDS CLARIFICATION] 마커만 허용
• 품질 체크리스트 자동 생성

1. /speckit.clarify - 명확화 (Optional)

• 최대 5개 질문만 (우선순위: 범위 > 보안 > UX > 기술)
• 각 질문에 추천 옵션 제공
• 답변 즉시 spec.md에 반영

1. /speckit.plan - 구현 계획

• constitution.md 원칙 준수 검증
• research.md - 기술 결정 및 근거
• data-model.md - 엔티티 설계
• contracts/ - API 스펙

1. /speckit.tasks - 작업 분해

• User Story 기반 Phase 구성
• 의존성 순서 정렬
• 병렬 실행 가능 태스크 [P] 표시
• 체크리스트 형식: - [ ] T001 [P] [US1] 설명 + 파일경로

1. /speckit.analyze - 일관성 검증 (Optional)

• 읽기 전용 (파일 수정 안 함)
• 누락된 요구사항 감지
• constitution 위반 = CRITICAL

1. /speckit.implement - 자동 구현

• 체크리스트 완료 여부 확인
• TDD: 테스트 먼저 → 구현 → 커밋
• 작업 완료 시 [X]로 자동 체크

각 명령어에는 이러한 복잡한 작업들을 수행하는 정교한 프롬프트가 내장되어 있습니다.

개발자는 복잡한 프롬프트 작성 대신, 무엇을 만들지 순수한 의도 전달에만 집중하면 됩니다.
개인의 프롬프트 작성 능력과 무관하게, 맥락을 충분히 제공하는 것만으로도 의도한 대로 정확한 구현이 가능합니다.

추천 도구 : spec-kit, task-master-ai

SDD 방법론을 적용한 API 구현 예시 (spec-kit 활용)

SDD 도구 중 하나인 spec-kit 을 이용해서 개발한 API PR을 살펴보겠습니다.
명세 기반 개발을 위한 AI 워크플로우 도구로 Specification → Plan → Tasks → Implementation 단계로 구조화 되어있다는 특징이 있습니다. (spec-kit 외에도 task-master 등 다양한 도구들이 있습니다.)

아래 펼치기를 통해 확인하실 수 있습니다.
spec-kit 사용하지 않으신 분들은 실제 사례를 통해, ‘나에게 정말 도움이 될까?’ 살펴보실 수 있습니다.

(1) 명세서 작성하기

 ▐▛███▜▌   Claude Code v2.0.25
▝▜█████▛▘  Opus 4.1 · Claude Max
  ▘▘ ▝▝    /Users/hannah/workspaces/my-project

────────────────────────────────────────────────────────────────────────────────────
# 명세 작성 - 무엇을, 왜
> /specify ExampleEntity을 읽어서 {uuid}/pre-application API를 완성해보자.
  ...

# 구현 계획
> /plan
  ...

# 작업 세분화
> /tasks
  ...
────────────────────────────────────────────────────────────────────────────────────

API 구현 시에는 API 인터페이스를 맥락으로 제공하는 것이 효과적이므로, Mock API와 참조해야하는 핵심 Entity 1개에 대한 정보만 제공하였습니다.
Mock API 대신 json이나 간단한 문서 형태를 전달해도 잘 이해합니다.

@RestController
@RequestMapping("/inventories")
class InventoryUiSchemaController {
    @GetMapping("{uuid}/ui-schema/pre-application")
    fun getPreApplicationSchema(): MarketingSlotApiSimpleResponse {
        // 사전신청 없으면 NotFound
        return MarketingSlotApiSimpleResponse(
            data =
                PreApplicationCreateUiSchemaResponse(
                    eventName = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    adAccountIds = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    requestedStartDateTime = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    requestedEndDateTime = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    specialNotes = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    targetRevenue = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    planningScale = PreApplicationCreateUiSchemaResponse.CommonAttributeSchema(),
                    additionalAttributes = null,
                ),
        )
    }
}

명령어 수행 결과로 아래와 같은 파일들이 생성됩니다.

(2) 구현하기

구현 시 spec-kit의 /implement 명령어을 이용한다면, 기존에 작성한 명세 문서들을 자동으로 활용하여 구현합니다.

이전 코드에서는 API Request, Response만 존재할뿐, 서비스도 없었습니다.
1번, 2번 명령어를 통해 명세(spec)을 구체화한 뒤 작업을 요청하였기에 기대한 구현 결과를 얻을 수 있습니다.

(3) Jira 티켓에 갱신

야무지게 만들어진 명세서, 이대로 휘발성으로 날리기에는 아쉽지 않나요?

Spec-kit이 생성한 spec.md와 tasks.md는 구현을 위한 명세서이자 최종 작업 결과에 대한 설명입니다. 이 문서를 요약해 Jira 티켓에 최종 반영함으로써 다음과 같은 이점을 얻을 수 있습니다.

• 지식의 영구 보존: 코드는 변경되지만, 무엇을 의도했는지에 대한 명확한 명세가 Jira 티켓에 남습니다. 향후 QA, PM, 신규 개발자가 이 기능을 다시 확인할 때 PR과 코드 베이스 전체를 탐색할 필요 없이 Jira 티켓 하나로 모든 맥락을 파악할 수 있습니다.
• 협업의 효율화: Spec-kit에 포함된 /summarize 등 요약 기능을 활용하거나, 직접 핵심 비즈니스 규칙과 최종 구현 결정 사항을 발췌하여 Jira 댓글 혹은 본문에 갱신해달라고 AI에게 요청합니다.
• 💡 적용 예시: /summarize spec.md and tasks.md and update jira ticket #1234
• 검증의 편의성: PM/PO가 Jira 티켓만 보고도 최종 구현 결과가 요구사항을 충족했는지 명세를 통해 빠르고 쉽게 확인할 수 있습니다.

Atlassian MCP 추가하기

claude mcp add --transport sse atlassian https://mcp.atlassian.com/v1/sse

여전히 남아있는 컨텍스트 제공 문제

프롬프트 엔지니어링 문제는 Step1에서 SDD 도구를 통해 해결했습니다.
하지만 여전히 컨텍스트 제공에 대한 문제는 남아있습니다.

AI와 일을 잘 하기 위해서는 충분한 컨텍스트 제공에 대한 방법도 고민해야합니다.

그렇다면 명세서를 컨텍스트로 재활용할 수 없을까?

명세서는 특정 작업을 위한 명세서이자 구현을 위한 최고의 프롬프트입니다.
하지만 컨텍스트 문제 해결을 위해 명세서를 그대로 재활용하면 다음과 같은 리스크에 노출됩니다.

• 최신화 실패 : 일회성 명세 문서는 시간이 지날수록 쌓이기만 하고 최신화되지 않습니다. Outdated되어 최신 정책을 반영하지 못해 재활용이 불가능합니다.
• 지식의 파편화 : 도메인 지식이 N개의 명세 문서에 흩어져 있습니다. 어떤 문서가 최신이고 정확한지 판단하기 어렵습니다.

때문에 일회성 작업 명세서(spec.md, tasks.md 등)들은 .gitignore에 추가하여 폐기합니다.

핵심은 팀 SSOT 구축

일회성 작업 명세서에서 끝나는 것이 아니라,
그 안에 담긴 도메인 컨텍스트를 팀의 영구적인 지식 자산으로 전환해야 합니다.
이 과정을 통틀어 CI-SDD (Continuously Integrated Spec-Driven Development)라고 표현합니다.

---

Step 2. 팀 SSOT의 지속적 통합 (CI-SDD) 😎

CI-SDD란?

Step 2에서는 컨텍스트 제공 문제를 해결합니다.

CI/CD가 "코드의 지속적 통합"을 의미하듯이,
이 글에서 CI-SDD는 SDD를 넘어 팀 SSOT(Single Source of Truth)로의 지속적 통합을 의미합니다. (😉 개발자에게 개념을 직관적으로 이해시키기 위해 가상의 단어입니다)

선순환 구조의 지속적인 지식 통합

명세를 통해 정확한 구현을 하는 것(Step 1)을 넘어,
그 지식을 통합하고 축적하여 팀의 단일 진실 원천 자산으로 만들어내는 것(Step 2)까지 포함한 흐름을 설명합니다.

흐름 설명

1. 작업에 필요한 풍부한 맥락을 제공
   • SDD 도구 덕분에 프롬프트 엔지니어링에 대한 고민 불필요
   • 무엇을 만들지에 대한 맥락 제공에 집중
2. AI는 사용자가 입력한 프롬프트와 팀의 SSOT 문서를 활용
3. 명세를 기반으로 구현 완료
4. 팀 SSOT 문서 최신화
   1. 새롭게 발견/변경된 도메인 지식을 팀 SSOT 문서에 반영
5. 다음 작업 시 AI가 더 완벽한 컨텍스트를 가지고 작업 시작!

🔁 시간이 지날수록…

• 팀의 SSOT의 품질 ↑
• 개발자가 제공해야할 맥락과 노력 ↓ (이미 SSOT 문서에 있는 내용)
• AI의 품질 ↑ (SSOT를 기반으로 일관된 출력)

문서 관리 예시

프로젝트 구조

CLAUDE.md

작업 전 .team/prd 문서를 읽고, 작업 후 문서 최신화할 것을 명시하세요. Claude Code의 경우 CLAUDE.md 를 시스템 프롬프트로서 항상 작업전에 읽고 시작합니다. AI Agent별로 약속된 시스템 프롬프트에 작성하시면 됩니다.

PR 리뷰 시, AI에게 팀 SSOT 문서 검토 요청

AI PR 코드 리뷰 시에, 작업한 내용이 팀 SSOT 문서에 정책 반영이 되어있는지 혹은 문서와 다른 코드 반영이 있는지 등을 검토 요청합니다. 이 덕분에 코드가 변경되는 시점마다 문서가 최신화되었는지 작업자와 동료가 인지할 수 있도록 합니다.

AI PR 피드백 결과

활용하기

팀 SSOT 문서를 활용한다면 개발자는 간결한 지시로도 AI에게 풍부한 컨텍스트를 제공할 수 있습니다.

Before : 개인의 지식에 의존

PreApplicationController에 제출 API를 구현해줘. 사전신청서는 이벤트명, 광고계정ID, 요청 시작일시, 종료일시가 필요하고, 제출 시 Validation 로직은 CommonAttribute와 AdditionalAttribute에 있는... (30줄 설명)

→ 개발자가 인지하고 있는 범위의 맥락만 제공
→ 팀원마다 차이 발생

After : 팀 SSOT 문서 활용

.team/prd/사전신청서 생성 문서.md를 참조해서 PreApplicationController에 제출 API를 구현해

→ 팀 SSOT 문서에 정리된 완벽한 컨텍스트를 AI가 활용
→ 모든 팀원이 상향 평준화된 AI 품질 획득

팀 SSOT 문서가 쌓였기 때문에 짧은 프롬프트 요청만으로 원하던 요구사항을 충족한 API를 뚝딱 만들 수 있었습니다.

---

맺음말: 프롬프트 + 팀 SSOT = 완벽한 협업 💪

AI와 잘 일하려면 두 가지가 필요합니다.

1. 프롬프트 엔지니어링 (How to Ask) → Step 1 (SDD): 도구를 통한 구조화된 프롬프트 활용
2. 충분한 컨텍스트 (What to Give) → Step 2 (CI-SDD): 선순환 구조의 팀 SSOT 문서 관리 체계 구축

이 글에서 제안하는 CI-SDD(Step 1 + Step 2)는 단순한 문서 작업이 아니라, AI 시대에 소프트웨어 개발팀이 가질 수 있는 가장 강력한 경쟁력입니다.

첫째, 팀의 일관된 품질을 보장합니다.
개개인이 알고 있는 컨텍스트가 아닌, 팀 전체가 공유하는 단일 진실의 원천(Single Source of Truth)을 AI에게 제공함으로써, 개인 역량 차이에 관계없이 일관되고 높은 품질의 AI Output을 확보하게 됩니다. 이는 디버깅과 재작업 비용을 획기적으로 줄여주는 미래를 위한 투자입니다.

둘째, 지식의 복리 효과를 만듭니다.
일회성 명세가 아닌, 살아있는 도메인 지식 베이스를 구축하여 프로젝트의 핵심 자산을 영구적으로 보존합니다. 이는 시간이 지날수록 지식의 선순환 구조를 만들어 도메인 문서 품질과 AI의 개발 효율이 동시에 상승하는 복리 효과를 가져옵니다.

셋째, 지속 가능한 개발을 가능하게 합니다.
지속 가능한 도메인 관리를 통해, 티켓 단위의 빠른 성과를 넘어 프로젝트 전체의 안정성과 지속 가능성을 확보할 수 있습니다.

🚀 AI와 더 정확하고 빠르게 일해봅시다 🚀

제안하는 액션

1. SDD 도구 설치하기 (spec-kit, task-master-ai를 추천합니다)
2. 작업마다 SDD 적용하기
3. 팀 SSOT 문서 작성하기