[SDD Plugin] 적용한 엔지니어링 — AI 엔지니어링 4가지 패러다임으로 분석

개요

SDD(Spec-Driven Development) Plugin은 Claude Code용 플러그인으로, GitHub Issue 기반의 4단계 프로세스(분석→설계→구현→테스트)를 통해 AI와 체계적으로 협업할 수 있도록 도와줍니다. 이번 포스트에서는 한 발 뒤로 물러나서, 이 플러그인에 어떤 AI 엔지니어링 원리가 적용되었는지 분석해 봅니다.

SDD Plugin의 전체 구조와 사용법은 SDD Plugin의 전체 구조와 사용법에서, 만들게 된 배경은 AI 코딩의 함정과 해결 방향에서, 개발 과정은 프로토타입에서 완성까지에서 다루고 있습니다.

AI 엔지니어링 4가지 패러다임에 대한 자세한 설명은 AI 엔지니어링 4가지 패러다임 — Prompt, Context, Agentic, Harness를 참고해 주세요.

Prompt Engineering — 범위를 제한하는 지시

SDD Plugin에서 가장 중요한 프롬프트 엔지니어링은 What/Why와 How를 분리하는 것이었습니다.

AI는 질문을 받으면 곧바로 기술적인 구현 방법(How)을 이야기하려는 경향이 있습니다. 하지만 What/Why가 정리되지 않은 상태에서 How를 논의하면 방향이 어긋날 수 있습니다.

analyze.md에서는 이를 명시적으로 차단합니다.

Focus ONLY on What and Why. Do NOT discuss How (technical implementation).

이 한 줄이 AI의 행동을 크게 바꿉니다. 분석 단계에서는 요구사항의 본질에만 집중하고, 기술적 논의는 설계 단계로 자연스럽게 넘어갑니다.

또한 각 단계별 산출물 템플릿도 프롬프트 엔지니어링의 일부입니다. 템플릿이 출력 형식을 미리 정해두기 때문에, AI가 일관된 구조로 결과를 만들어냅니다.

## 요약

- 요청 유형:
- 한 줄 요약:
- 요청 배경:

## 기능 목록

| # | 기능 | 설명 |

Context Engineering — 필요한 정보만 로드하는 구조

SDD Plugin에서 Context Engineering이 적용된 곳은 크게 두 가지입니다.

SKILL.md의 모듈화

개발 과정 포스트에서도 언급했지만, 처음에는 모든 프로세스를 SKILL.md 하나에 넣었습니다. 하지만 이렇게 하면 /sdd analyze를 실행할 때 test.md의 내용까지 전부 컨텍스트에 로드됩니다.

# 변경 전: 모든 프로세스가 하나의 파일에
SKILL.md (500줄) → 전부 컨텍스트에 로드

# 변경 후: 라우터 + 개별 명령어 파일
SKILL.md (라우터, ~60줄) → commands/analyze.md만 추가 로드

11개 명령어가 있지만, 한 번에 1개만 컨텍스트에 들어갑니다. 토큰 사용량이 줄어들고, AI가 불필요한 정보에 혼란스러워하는 것도 방지됩니다.

GitHub에서 필요한 산출물만 가져오기

설계 단계에서는 분석 결과가 필요하고, 구현 단계에서는 설계 결과가 필요합니다. 이때 Issue의 모든 comment를 가져오는 것이 아니라, 마커를 사용해 필요한 산출물만 필터링합니다.

# 모든 코멘트를 컨텍스트에 넣는 대신
gh api .../comments --jq '.[].body'

# 마커가 포함된 코멘트만 가져옴
gh api .../comments --jq '.[] | select(.body | contains("sdd:analyze:output")) | .body'

Issue에 일반 대화 코멘트가 수십 개 달려있어도, 산출물 마커가 있는 코멘트만 정확히 가져올 수 있습니다.

Agentic Engineering — 에이전트와 반복 루프

SDD Plugin에서 가장 눈에 띄는 Agentic Engineering 기법은 역할별 에이전트 분리와 자기 개선 루프입니다.

탐색 전용 에이전트

설계 단계에서 기존 코드베이스를 분석할 때, 메인 에이전트가 직접 하지 않고 전용 탐색 에이전트를 위임합니다.

Explore the codebase using a dedicated Explore agent (model: "sonnet")

탐색 작업은 빠른 모델(Sonnet)로도 충분하기 때문에, 비용과 속도를 최적화할 수 있습니다. 메인 에이전트는 탐색 결과를 받아서 설계에 집중합니다.

AI 리뷰 루프

모든 단계의 산출물은 ai-review.md에 정의된 독립 리뷰 루프를 거칩니다.

Execute the following loop (maximum 3 rounds):

1. Self-Review: 스스로 산출물을 검토
2. AI Review: 독립 에이전트가 별도로 검토
3. Evaluate: 통과 여부 판단
   → 통과하면 종료, 실패하면 수정 후 다음 라운드

핵심은 리뷰하는 에이전트가 작업한 에이전트와 독립적이라는 것입니다. 자기가 만든 결과를 자기가 리뷰하면 놓치는 부분이 있을 수 있지만, 별도의 에이전트가 리뷰하면 다른 관점에서 문제를 발견할 수 있습니다.

리뷰 기준도 단계별로 다릅니다.

단계	리뷰 기준
analyze	기능이 명확하게 정의되었는가? What/Why가 충분한가? 빠진 요구사항은 없는가?
design	설계가 요구사항과 일치하는가? 실현 가능한가? 아키텍처와 일관성이 있는가?
implement	코드 품질은? 테스트 커버리지는? 패턴 일관성은? PR 설명이 정확한가?
test	테스트 커버리지가 충분한가? 엣지 케이스가 다뤄졌는가? 리그레이션 리스크는?

Harness Engineering — 실행 환경 설계

SDD Plugin 자체가 하나의 Harness라고 볼 수 있습니다. AI가 작업하는 프로세스, 순서, 제약 조건을 미리 정의해 두는 것이니까요.

선언형 프로세스 제어

코드로 AI를 제어하는 것이 아니라, Markdown으로 프로세스를 선언합니다. SKILL.md가 “이 명령어가 들어오면 이 파일을 읽어라”고 안내하고, 각 command 파일이 “이 단계에서는 이것을 하고, 저것은 하지 마라”고 제약합니다.

이 방식의 장점은 프로세스 수정이 매우 쉽다는 것입니다. Markdown 파일만 편집하면 AI의 행동이 바뀝니다. 코드를 수정하고, 빌드하고, 배포하는 과정이 필요 없습니다.

GitHub 기반 상태 관리

라벨로 진행 상태를 관리하는 것도 Harness Engineering입니다. AI가 임의로 단계를 건너뛰거나 이미 완료된 단계를 다시 실행하는 것을 라벨 체크로 방지합니다.

sdd:analyze → sdd:design → sdd:implement → sdd:test → sdd:done

rollback 명령어도 마찬가지입니다. 이전 단계로만 돌아갈 수 있고, 앞으로 건너뛸 수는 없습니다. AI에게 자유를 주되, 프로세스의 순서는 환경이 강제합니다.

권한 설정

Claude Code의 settings.json을 통해 AI의 권한을 제한할 수도 있습니다.

{
  "permissions": {
    "allow": [
      "Bash(ls:*)",
      "Bash(wc:*)",
      "Read(/path/to/sdd-plugin/skills/sdd/**)"
    ]
  }
}

읽기 전용 bash 명령만 허용하고, 스킬 파일만 읽기 가능하도록 제한하면 안전하게 플러그인을 사용할 수 있습니다.

4가지 패러다임이 만나는 지점

SDD Plugin을 4가지 패러다임으로 분석해 보면, 각각이 독립적으로 작용하는 것이 아니라 서로 맞물려서 동작한다는 것을 알 수 있습니다.

패러다임	SDD Plugin에서의 역할
Prompt	What/Why와 How 분리, 산출물 템플릿으로 출력 형식 제어
Context	SKILL.md 모듈화, 마커 기반 산출물 필터링
Agentic	탐색 에이전트 위임, 독립 리뷰 루프 (최대 3라운드)
Harness	선언형 프로세스, 라벨 기반 상태 관리, 권한 설정

예를 들어 analyze 명령어를 실행하면:

Harness: 라벨을 확인하여 올바른 단계인지 검증
Context: Issue body에서 요구사항을 읽고, 필요한 산출물만 컨텍스트에 로드
Prompt: “What/Why만 분석하세요, How는 논의하지 마세요”로 범위 제한
Agentic: AI가 분석을 수행하고, 독립 에이전트가 리뷰하는 루프 실행

4가지 레이어가 하나의 명령어 안에서 동시에 작동합니다.

완료

이번 포스트에서는 SDD Plugin에 적용된 AI 엔지니어링 기법을 4가지 패러다임으로 분석해 보았습니다.

SDD Plugin을 만들면서 가장 크게 느낀 것은, AI를 잘 활용하려면 프롬프트 하나만 잘 쓰는 것으로는 부족하다는 것이었습니다. 정보를 어떻게 관리하고(Context), 에이전트를 어떻게 구성하며(Agentic), 어떤 환경에서 실행시킬지(Harness)까지 함께 설계해야 비로소 AI가 안정적으로 좋은 결과를 만들어냅니다.

AI와 함께 개발 프로세스를 고민하시는 분들께 도움이 되었으면 좋겠습니다.