Reflection SDD: Reflection Harness를 사용하여 OpenSpec 워크플로우 수준 높이기

잘못된 스펙 파일이 코드 품질을 떨어뜨리게 방치하지 마세요.

서론 (Introduction)

이 글에서는 제가 OpenCode 내부의 OpenSpec 워크플로우에 어떻게 성찰 메커니즘 (reflection mechanism)을 도입했는지, 그리고 그것이 어떻게 AI가 생성한 코드의 품질을 극적으로 향상시켰는지에 대해 설명하고자 합니다.

약 한 달간의 테스트를 거친 결과, 이 성찰 (reflection) 워크플로우를 통해 OpenCode 내의 DeepSeek-V4-pro가 Claude Opus 4.6과 거의 비슷한 수준으로 성능을 발휘하게 되었습니다. 유일한 비용은 약간의 추가 검토 시간과 조금 더 많은 토큰 (tokens)뿐입니다. 저를 믿으세요, 그만한 가치가 있습니다.

어떻게 하는지 궁금하신가요? 바로 시작해 봅시다.

이것이 작동하는 이유 (Why This Works)

저는 한동안 AI 코딩을 사용해 왔습니다. Claude Code와 비교했을 때, 저는 OpenCode와 OpenSpec을 사용하여 저만의 SDD 기반 코딩 워크플로우를 구축하는 것을 선호합니다. 저는 이 OpenCode 워크플로우에 대해 구체적으로 다룬, 좋은 반응을 얻었던 글을 작성한 적이 있습니다:

How I Use OpenCode, Oh-My-OpenCode-Slim, and OpenSpec to Build My Own AI Coding Environment

OpenSpec과 explore → propose → apply → verify → archive 워크플로우 루프를 통해, 우리는 마침내 LLM이 복잡한 프로젝트 개발을 처리하도록 만들 수 있습니다.

With the OpenSpec workflow loop, LLMs can finally write usable code. Image by Author

하지만 여러분도 아마 겪어보셨겠지만, SDD 워크플로우를 사용하더라도 GPT 5.5든 최신 DeepSeek-V4-pro든 어떤 모델을 사용하든, AI는 여전히 필연적으로 숨겨진 버그를 생성하거나 지저분한 코드를 쌓아 올립니다. 제가 프로덕션 (production) 환경에 안심하고 넣을 수 없는 코드 말이죠.

저의 첫 번째 해결책은 /opsx-apply 단계 이후에 @reviewer 서브 에이전트 (sub-agent)를 호출하여 변경 사항에 대해 코드 리뷰 (code review)를 수행하는 것이었습니다. 때로는 이것이 작동하여 아키텍처 (architectural) 또는 구현 (implementation) 문제를 잡아내기도 했습니다. 하지만 그 영향은 제한적이었습니다.

종종 프로젝트를 한동안 사용한 후에야 무언가 잘못되었다는 것을 발견하곤 했습니다. 특정 시나리오가 커버되지 않았거나, 엣지 케이스 (edge cases)를 놓쳤거나, 코드의 한 부분은 업데이트되었지만 관련 모듈은 업데이트되지 않은 경우 등이 그러했습니다.

나중에 저는 한 걸음 물러나 전체 AI 코딩 워크플로우 (workflow)를 다시 살펴보았고, 그때 진짜 문제를 발견했습니다.

프로그래머로서 우리는 항상 우리 코드가 좋은지에 집중하기 때문에, 자연스럽게 코드 레벨 (code level)에서 사안을 바라보게 됩니다.

하지만 우리는 OpenSpec이 생성하는 제안 파일 (proposal files)의 품질을 완전히 간과하고 있었습니다. 요구사항 논의를 마치고 제안 파일을 생성한 다음, 그냥 AI가 구현을 시작하도록 내버려 두었습니다. 이것이 바로 입력 레벨 (input-level)의 버그가 유입되는 방식입니다. 문제가 발생하면 우리는 모델 (model)을 탓합니다.

생각해 보세요. 전통적인 코딩 시대에 제품 관리자 (product manager)가 요구사항 문서 (requirements doc)를 전달했을 때, 코딩을 시작하기 전의 중요한 단계가 있었습니다. 바로 요구사항 검토 (requirements review)입니다. 요구사항 문서나 설계 문서 (design doc)의 모든 문제가 해결될 때까지 우리는 키보드에 손을 대지 않았습니다.

그렇다면 왜 AI 코딩 시대에는 이 단계를 잊어버린 걸까요? 그것이 바로 오늘 우리가 해결하고자 하는 문제입니다. OpenSpec 워크플로우에 요구사항 검토 단계를 다시 추가하고, 이것이 AI가 생성한 코드를 더 좋게 만드는지 확인해 보겠습니다.

구현 방법

SDD 워크플로우는 특별한 것이 아닙니다. 멀티 에이전트 시스템 (multi-agent system) 디자인 패턴에 익숙하다면, SDD가 기본적으로 plan-execute 패턴이라는 것을 알 수 있을 것입니다.

한 에이전트가 사용자의 작업을 단계별 계획 파일 (plan file)로 나누면, 다른 에이전트가 그 계획을 따라 작업을 수행합니다. 이를 통해 에이전트 시스템이 복잡한 업무를 처리할 수 있게 합니다.

The Plan agent makes the plan, the Executor agent gets it done. Image by Author

하지만 plan-execute 설정에서 에이전트가 생성하는 결과물의 품질을 어떻게 보장할 수 있을까요? 바로 그 지점에서 reflection (성찰)이라고 불리는 패턴이 등장합니다.

성찰 (reflection) 패턴은 멀티 에이전트 워크플로우 (multi-agent workflow)에 성찰 에이전트 (reflection agent)를 추가합니다. 이 에이전트는 일반적으로 완전히 다른 LLM (Large Language Model)에서 실행되며, plan (계획) 또는 executor (실행) 에이전트의 결과물을 다른 관점에서 검토하여 멀티 에이전트 시스템의 전반적인 성능을 높입니다.

성찰 패턴은 콘텐츠 생성 및 심층 연구 시나리오에서 널리 사용되고 있으며, 이는 그 효과가 입증되었음을 의미합니다.

Just adding a reflection step can dramatically improve task quality. Image by Author

이 패턴이 검증되었으므로, 우리는 제안 파일 (proposal files)을 대상으로 OpenSpec 워크플로우에 동일한 성찰 단계를 도입할 수 있습니다.

기본 에이전트와는 다른 LLM에서 실행되며, 제안 파일을 다른 관점에서 검토하는 성찰 에이전트를 소개하겠습니다. 또한 이 성찰 에이전트가 워크플로우 내에서 능동적인 역할을 수행할 수 있도록 OpenSpec 워크플로우를 조정할 것입니다.

성찰 에이전트 소개

OpenCode에 새로운 에이전트를 추가하는 방법은 간단합니다. 에이전트의 프롬프트 (prompt)가 담긴 새로운 마크다운 (Markdown) 파일을 ~/.config/opencode/agents/ 디렉토리에 넣기만 하면 됩니다.

이 에이전트의 핵심 작업은 명확합니다. OpenSpec이 생성하는 아티팩트 (artifact) 파일들을 다각도에서 검토하여, 요구사항 입력의 품질이 처음부터 견고한지 확인하는 것입니다. 이 에이전트는 /opsx-propose 단계와 /opsx-apply 단계 사이에 위치합니다.

Only proposals that pass review can move on to the apply phase. Image by Author

deepseek-v4-pro를 사용하여 이 에이전트 프롬프트의 초안을 생성할 수 있습니다:

당신은 **OpenSpec 변경 검토자 (OpenSpec Change Reviewer)** — 실질적인 내용에 집중하는 비판적 사고가이자 감사관입니다.

당신의 임무는 OpenSpec 변경 사항이 구현 단계로 넘어가기 전에 모든 아티팩트를 검토하고, 실제로 구현 실패나 재작업을 유발할 수 있는 문제를 찾아내는 것입니다.
...

explore → /opsx-propose → ⬅ 현재 위치 (여러 라운드가 반복될 수 있음) → /opsx-apply → verify → archive


스펙 (Spec)은 아직 확정되지 않았습니다. 구현 (Implementation)은 시작되지 않았습니다. 여러분의 임무는 **코드가 작성되기 전에 실제로 재작업이나 장애를 유발할 수 있는 결함 (Defects)을 찾아내는 것**입니다. 스펙 오류를 잡아내는 데는 몇 분이 걸리지만, 잘못된 코드를 수정하는 데는 몇 시간이 걸립니다.

...

제안 (Proposals)을 다른 각도에서 검토하고 성찰 (Reflection)의 품질을 높이기 위해, 메인 에이전트 (Main Agent)가 사용하는 것과 다른 LLM을 성찰 에이전트 (Reflection Agent)로 사용할 것을 권장합니다. 예를 들어, 저의 기본 코딩 에이전트는 deepseek-v4-pro를 사용하므로, 성찰 에이전트는 kimi k2.6을 사용합니다.

---
description: OpenSpec Change Reviewer — propose 이후 및 apply 이전 단계에서, 변경 사항에 포함된 모든 아티팩트 (Artifact) 파일(proposal/design/specs/tasks)을 비판적으로 검토합니다.
mode: subagent
...

OpenSpec 워크플로우 고정하기

OpenSpec은 실제로 고정된 워크플로우 설계를 가지고 있지 않으며, 사용자는 기본 SDD 베스트 프랙티스 (Best Practice)를 따릅니다. 따라서 첫 번째 단계는 이 워크플로우를 고정하여, OpenCode가 코드를 작성하기 전에 OpenSpec 제안 (Proposal)을 먼저 작성하도록 만드는 것입니다.

---
name: openspec-workflow
description: 모든 OpenSpec 작업의 필수 전제 조건 — 어떤 openspec-* 스킬 (Skill)을 사용하기 전에 이를 먼저 로드하십시오. /opsx-apply, /opsx-propose, /opsx-verify, /opsx-archive, /opsx-explore, /opsx-sync를 실행할 때; `openspec status`, `openspec list`, `openspec instructions`를 실행할 때; `openspec/changes/` 하위의 파일을 읽을 때; 또는 모든 OpenSpec 단계(propose, apply, verify, archive, explore, sync)를 수행할 때 사용하십시오.
...

이 워크플로우를 프로젝트의 AGENTS.md 파일에 넣어 OpenCode가 일관되게 따르도록 할 수 있습니다. 또는 글로벌 ~/.config/opencode/AGENTS.md 파일에 넣어 모든 프로젝트마다 설정할 필요가 없도록 할 수도 있습니다.

더 나은 옵션은 워크플로우를 하나의 스킬 (Skill)로 전환하여, OpenCode가 OpenSpec을 사용할 때만 이 워크플로우 정의를 로드하도록 하는 것입니다. 저는 전체 워크플로우를 openspec-workflow 스킬로 패키징해 두었으며, 기사 끝부분에서 소스 파일을 가져갈 수 있습니다.

워크플로우에 성찰 에이전트 (reflection agent) 삽입하기

OpenSpec 워크플로우가 하나의 스킬 (skill)로 고정되면, 모든 SDD 코딩 세션은 '스펙 우선, 코드 후순위 (spec-first, code-second)' 프로세스를 따르게 됩니다. 즉, /opsx-propose 및 /opsx-apply 단계가 진행됨을 의미합니다.

앞서 언급했듯이, 성찰 에이전트 (reflection agent)는 이 두 단계 사이에 위치하여, 구현이 시작되기 전에 제안 파일 (proposal files)의 품질을 검토합니다. 성찰 패턴 (reflection pattern)을 따라, 이 검토 및 수정 (review-and-fix) 사이클은 제안 산출물 (proposal artifacts)에 심각한 문제가 없을 때까지 여러 차례 반복될 수 있습니다.

무한 루프를 방지하기 위해, 검토 라운드 횟수에 대한 엄격한 제한 (hard cap)이 필요합니다. openspec-workflow의 SKILL.md 파일을 업데이트하여 성찰 프로세스를 추가해 보겠습니다.

### OpenSpec 성찰 프로세스 (OpenSpec Reflection Process)

1. **각 산출물 배치가 생성된 후**, `@openspec-reviewer` 에이전트를 호출하여 **해당 배치의 산출물 파일들을 반드시** 검토해야 합니다.
...

이 시점에서 OpenSpec 제안을 위한 전형적인 성찰 프로세스가 마련되었습니다. 여러분이 할 일은 /opsx-propose를 실행하고, 커피를 한 잔 마시며 성찰 에이전트가 제안 내용을 점진적으로 개선할 때까지 기다리는 것뿐입니다.

After the OpenSpec proposal is created, the openspec-reviewer agent will be automatically invoked to begin reviewing and fixing it. Image by Author

몇 차례의

탐색 (explore) 단계에서의 논의 사항이 파일로 저장되도록 요구하여, 제안서 생성 및 검토 프로세스가 체크리스트 기준점 (checklist baseline)을 가질 수 있도록 하겠습니다.
모든 파일이 생성될 때까지 기다렸다가 검토를 시작하는 대신, 한 번에 하나의 파일을 검토하겠습니다.
각 검토 라운드의 로그 (logs)를 저장하여, 다음 라운드에서 사용하거나 누군가 수동으로 개입해야 할 때 사용할 수 있도록 하겠습니다.

또한, Reflection 에이전트 (reflection agent)와 OpenSpec 워크플로우 스킬 (OpenSpec Workflow skill)의 전체 소스 파일도 포함했습니다.

관심이 있으신가요? 여기를 클릭하여 계속 읽어보세요.