AI 코딩 어시스턴트의 환각 문제: OpenSpec으로 사양 기반 개발을 달성하는 방법

2026. 4. 2.

AI 코딩 어시스턴트의 환각 문제: OpenSpec으로 사양 기반 개발을 달성하는 방법

AI 코딩 어시스턴트는 강력하지만, 종종 실제 요구사항과 맞지 않거나 프로젝트 규칙을 위반하는 코드를 생성합니다. 이 글에서는 HagiCode 프로젝트가 OpenSpec 워크플로우를 사용하여 사양 기반 개발을 구현하고, 구조화된 제안 메커니즘을 통해 AI 환각의 위험을 크게 줄이는 방법을 공유합니다.

배경

GitHub Copilot이나 ChatGPT를 사용하여 코드를 작성해 본 사람이라면 아마 이 경험이 있을 것입니다. AI가 생성한 코드는 면져 보이지만, 실제로 사용해 보면 문제가 곳곳에서 나타납니다. 프로젝트의 잘못된 컴포넌트를 사용했을 수도 있고, 팀의 코딩 표준을 무시했을 수도 있으며, 존재하지도 않는 가정을 바탕으로 큰 덩어리의 로직을 작성했을 수도 있습니다.

이것이 소위 “AI 환각” 문제입니다. 프로그래밍에서 이것은 표면적으로는 합리해 보이지만 실제로는 프로젝트의 실제 상태에 맞지 않는 코드로 나타납니다.

이것에 대해 약간 답답한 점도 있습니다. AI 코딩 어시스턴트가 더 보편화될수록 문제는 더 심각해집니다. 결국 AI는 프로젝트의 기록, 아키텍처 결정, 코딩 규칙에 대한 이해가 부족하며, 너무 많은 자유를 주면 현실과 맞지 않는 코드를 “창의적으로” 생성합니다. 글을 쓰는 것과 비슷합니다. 구조가 없으면 상상의 세계로 빠지기 쉽지만, 실제 상황은 훨씬 더 현실적입니다.

이러한 문제를 해결하기 위해 우리는 대담한 결정을 내렸습니다. AI를 더 똑똘하게 만드는 대신, AI를 “사양”이라는 우리 안에 넣습니다. 이 결정이 가져온 변화는 예상보다 훨씬 클 수 있으며, 곧 설명하겠습니다.

HagiCode 소개

이 글에서 공유하는 접근 방식은 HagiCode 프로젝트의 실무 경험에서 나온 것입니다. HagiCode는 구조화된 엔지니어링 실무를 통해 AI 프로그래밍의 실제 문제를 해결하기 위해 노력하는 오픈소스 AI 코딩 어시스턴트 프로젝트입니다.

AI 환각의 근본 원인

해결책을 살펴보기 전에 먼저 문제가 실제로 어디서 오는지 살펴봅시다. 지자를 알고 적을 알면 백전백승이라는 말이 있습니다. AI에 적용해도 놀랍게 잘 맞습니다.

컨텍스트 부족

AI 모델은 공개 코드 저장소에서 학습되지만, 프로젝트는 자체 기록, 규칙, 아키텍처 결정을 가지고 있습니다. AI는 이러한 “암묵적 지식”에 직접 접근할 수 없으므로, 생성하는 코드가 종종 실제 프로젝트와 단절됩니다.

이것이 전적으로 AI의 잘못은 아닙니다. AI는 프로젝트 안에 살아본 적이 없으므로, 작성되지 않은 규칙을 어떻게 알 수 있겠습니까? 새로 온 인턴과 비슷합니다. 그곳의 관습을 모르는 것은 정상입니다. 유일한 문제는 비용이 꽤 높을 수 있다는 것입니다.

너무 많은 자유

AI에게 “사용자 인증 기능을 구현해 줘”라고 요청하면 거의 모든 형태의 코드를 생성할 수 있습니다. 명확한 제약이 없으면 AI는 프로젝트의 요구사항을 따르는 대신 자신이 “생각하는” 합리적인 방식으로 구현합니다.

프로젝트 표준을 배운 적이 없는 사람에게 자유롭게 즉흥하도록 요청하는 것과 같습니다. 그게 문제가 안 생길 리가 없겠습니까? AI가 무책임한 것이 아니라, 이 맥락에서 책임이 무엇을 의미하는지 모를 뿐입니다.

검증 부족

AI가 코드를 생성한 후, 구조화된 검토 프로세스가 없으면 거짓 가정에 기반한 코드가 바로 저장소에 들어갈 수 있습니다. 문제가 테스트나 심지어 프로덕션에서 발견되면 이미 비용이 너무 큽니다.

양을 잃고 나서 외양간을 고치는 것과 같습니다. 원칙은 명백하지만, 실제로는 추가 작업을 귀찮아하는 경우가 많습니다. 문제가 발생하기 전까지 누가 앞에 더 많은 시간을 쓰고 싶어 하겠습니까?

OpenSpec: 사양 기반 개발의 해답

HagiCode는 OpenSpec을 해결책으로 선택했습니다. 핵심 아이디어는 간단합니다: 모든 코드 변경은 구조화된 제안 워크플로우를 거쳐야 하며, 추상적인 아이디어를 실행 가능한 구현 계획으로 전환합니다.

거창하게 들릴 수 있지만, 쉽게 말하면 AI가 코드를 작성하기 전에 요구사항 문서를 작성하게 하는 것입니다. 옛말에 “준비는 성공의 어머니이고, 준비 없음은 실패의 어머니”라는 말이 있듯이 말입니다.

OpenSpec이란 무엇인가

OpenSpec은 npm 기반 명령줄 도구(@fission-ai/openspec)로, 표준화된 제안 파일 구조와 검증 메커니즘을 정의합니다. 간단히 말해 AI가 코드를 작성하기 전에 “요구사항 문서”를 작성하게 만드는 것입니다.

환각 방지 3단계 워크플로우

OpenSpec은 3단계 워크플로우를 통해 제안 품질을 보장합니다:

1단계: 제안 초기화 - 세션 상태를 Openspecing으로 설정합니다 2단계: 중간 처리 - Openspecing 상태를 유지하면서 점진적으로 산출물을 다듬습니다 3단계: 제안 완료 - Reviewing 상태로 전환합니다

이 설계에는 영리한 세부 사항이 있습니다. 첫 번째 단계는 ProposalGenerationStart 유형을 사용하며, 완료해도 상태 전환이 트리거되지 않습니다. 이는 전체 다단계 워크플로우가 완료되기 전에 검토 단계에 너무 일찍 진입하는 것을 방지합니다.

이 세부 사항은 사실 꽤 흥미롭습니다. 요리와 비슷합니다. 불이 제대로 오르기 전에 뚜껑을 열면 아무것도 잘 되지 않습니다. 한 걸음씩 인내심을 가지고 나아가야만 좋은 요리가 나옵니다.

// HagiCode 프로젝트의 구현
public enum MessageAssociationType
{
    ProposalGeneration = 2,
    ProposalExecution = 3,

    /// <summary>
    /// 3단계 제안 생성 워크플로우의 시작을 표시
    /// 완료해도 Reviewing 상태로 전환되지 않음
    /// </summary>
    ProposalGenerationStart = 5
}

표준화된 파일 구조

모든 OpenSpec 제안은 동일한 디렉토리 구조를 따릅니다:

openspec/
├── changes/                    # 활성 및 보관된 변경
│   ├── {change-name}/
│   │   ├── proposal.md        # 제안 설명
│   │   ├── design.md          # 설계 문서
│   │   ├── specs/             # 기술 사양
│   │   └── tasks.md           # 실행 가능한 작업 목록
│   └── archive/               # 보관된 변경
└── specs/                     # 독립 사양 라이브러리

HagiCode 프로젝트의 통계에 따르면 이미 4,000개 이상의 보관된 변경과 150,000줄 이상의 사양 파일이 있습니다. 이러한 역사적 축적은 AI에게 명확한 지침을 제공할 뿐만 아니라 팀에게 귀중한 지식 베이스를 제공합니다.

이것은 선대들이 남긴 고전과 비슷합니다. 충분히 읽으면 패턴이 보이기 시작합니다. 다만 이 고전들은 파일에 저장되어 있고 대나무 쪽에 쓰인 것이 아니라는 점이 다릅니다.

다중 계층 검증 메커니즘

시스템은 제안 품질을 보장하기 위해 여러 계층의 검증을 구현합니다:

// 필수 파일 존재 여부 검증
ValidateProposalFiles()

// 실행 전 전제 조건 검증
ValidateExecuteAsync()

// 시작 조건 검증
ValidateStartAsync()

// 보관 조건 검증
ValidateArchiveAsync()

// 제안 이름 형식 검증 (kebab-case)
ValidateNameFormat()

이러한 검증은 여러 검문소의 문지기와 같습니다. 정말 자격을 갖춘 제안만 통과할 수 있습니다. 번거로워 보일 수 있지만, 불량한 코드가 저장소에 들어가는 것보다는 훨씬 낫습니다.

프롬프트 템플릿 제약

AI가 HagiCode 내에서 실행될 때, 미리 정의된 Handlebars 템플릿을 사용합니다. 이 템플릿에는 명시적인 단계별 지시와 보호 가드레일이 포함됩니다. 예를 들어:

• 사용자의 의도를 이해하기 전에는 계속하지 마십시오
• 검증되지 않은 코드를 생성하지 마십시오
• 이름이 유효하지 않으면 사용자에게 다시 제공하도록 요구하십시오
• 변경이 이미 존재하면 다시 생성하는 대신 continue 명령을 사용하도록 제안하십시오

이러한 “쇠사슬 속에서 춤추는” 방식은 실제로 AI가 요구사항을 이해하고 표준을 따르는 코드를 생성하는 데 더 집중하도록 돕습니다. 제약은 항상 나쁜 것은 아닙니다. 때로는 너무 많은 자유가 바로 혼란을 만듭니다.

실무: 프로젝트에서 OpenSpec 사용하기

설치 및 초기화

npm install -g @fission-ai/openspec@1
openspec --version  # 설치 확인

openspec/ 폴더 구조가 프로젝트 루트에 자동으로 생성됩니다.

이 단계에서 특별히 신비한 것은 없습니다. 그저 도구 설치이며, 모두가 이해합니다. @fission-ai/openspec@1을 사용하는 것만 기억하십시오. 새 버전에는 함정이 있을 수 있으며, 안정성이 가장 중요합니다.

제안 생성

HagiCode 대화 인터페이스에서 단축 명령을 사용합니다:

/opsx:new

또는 변경 이름과 대상 저장소를 지정합니다:

/opsx:new "add-user-auth" --repos "repos/web"

제안 생성은 글을 쓰기 전에 개요를 잡는 것과 비슷합니다. 개요가 있으면 나머지가 훨씬 쉬워집니다. 많은 사람이 바로 쓰기 시작하는 것을 선호하지만, 중간쯤 가서 아이디어가 성립하지 않는다는 것을 깨닫게 됩니다. 그때가 진정 두통이 시작되는 때입니다.

산출물 생성

/opsx:continue를 사용하여 필요한 산출물을 단계별로 생성합니다:

proposal.md - 변경의 목적과 범위를 설명합니다

# Proposal: 사용자 인증 추가

## Why
현재 시스템에는 사용자 인증이 없어 민감한 API를 보호할 수 없습니다.

## What Changes
- JWT 인증 미들웨어 추가
- 로그인/가입 API 구현
- 프론트엔드 통합 업데이트

design.md - 상세 기술 설계

# Design: 사용자 인증 추가

## Context
현재 시스템은 공개 API를 사용하므로 누구나 접근할 수 있습니다...

## Decisions
1. Session 대신 JWT 선택...
2. HS256 알고리즘 사용...

## Risks
- 토큰 유출 위험...
- 완화 조치...

specs/ - 기술 사양 및 테스트 시나리오

# user-auth 사양

## Requirements

### Requirement: JWT 토큰 생성
시스템은 HS256 알고리즘을 사용하여 JWT 토큰을 생성해야 합니다(SHALL).

#### Scenario: 유효한 로그인
- WHEN 사용자가 유효한 자격 증명을 제공하면
- THEN 시스템은 유효한 JWT 토큰을 반환해야 합니다(SHALL)

tasks.md - 실행 가능한 작업 목록

# Tasks: 사용자 인증 추가

## 1. 백엔드 변경
- [ ] 1.1 AuthController 생성
- [ ] 1.2 JWT 미들웨어 구현
- [ ] 1.3 단위 테스트 추가

이러한 산출물은 글을 쓰기 위한 초안과 비슷합니다. 초안이 완료되면 본문이 자연스럽게 흐릅니다. 많은 사람이 초안 쓰는 것을 싫어하는데, 시간 낭비라고 생각하지만, 실제로는 가장 명확한 사고가 일어나는 곳이 종종 그곳입니다.

검토 및 적용

모든 산출물이 완료된 후:

/opsx:apply

AI가 모든 컨텍스트 파일을 읽고 tasks.md의 체크리스트에 따라 단계별로 작업을 실행합니다. 이 시점에서 사양이 이미 명확하므로 생성된 코드의 품질이 훨씬 높습니다.

이 단계에 이르면 절반은 이미 끝난 것입니다. 명확한 작업 목록이 있으면 나머지는 단계별로 실행하는 것뿐입니다. 문제는 많은 사람이 이전 단계를 건너뛰고 바로 여기로 뛰어든다는 것입니다. 그러면 당연히 품질을 보장하기 어렵습니다.

보관

변경이 완료된 후:

/opsx:archive

완료된 변경을 archive/ 디렉토리로 이동하여 나중에 검토하고 재사용할 수 있습니다.

보관은 중요합니다. 완성된 글을 소중히 보관하는 것과 같습니다. 미래에 비슷한 문제가 나타나면, 과거 기록을 뒤져보면 답을 찾을 수 있습니다. 많은 사람이 번거롭게 생각하지만, 이렇게 축적된 자료가 종종 가장 가치 있는 자산입니다.

참고 사항 및 모범 사례

제안 명명 규칙

kebab-case를 사용하고, 문자로 시작하며, 소문자, 숫자, 하이픈만 포함합니다:

• add-user-auth
• AddUserAuth
• add--user-auth

명명 규칙은 사소해 보일 수 있지만, 일관성은 항상 가치가 있습니다. 소프트웨어에서 일관성은 사람들이 항상 주의를 기울이지 않더라도 중요합니다.

일반적인 실수 피하기

1. 3단계 워크플로우의 1단계에서 잘못된 유형 사용 - 상태가 너무 일찍 전환됩니다
2. 마지막 단계에서 상태 전환을 트리거하는 것을 잊음 - 워크플로우가 Openspecing 상태에 갇힙니다
3. 검토를 건너뛰고 직접 실행 - 먼저 모든 산출물이 완료되는지 검증해야 합니다

이러한 실수는 모두 초보자에게 흔합니다. 경험자는 자연스럽게 피하는 방법을 압니다. 그래도 모두가 언젠가 경험자가 되고, 몇 번의 우회는 과정의 일부입니다. 다만 너무 많은 우회를 하지 않기를 바랄 뿐입니다.

다중 변경 관리

OpenSpec은 동시에 여러 제안을 관리하는 것을 지원하며, 대규모 기능에 특히 유용합니다:

# 모든 활성 변경 보기
openspec list

# 특정 변경으로 전환
openspec apply "add-user-auth"

# 변경 상태 보기
openspec status --change "add-user-auth"

여러 변경을 관리하는 것은 한 번에 여러 편을 쓰는 것과 비슷합니다. 약간의 기술과 인내심이 필요하지만, 익숙해지면 충분히 자연스러워집니다.

세션 상태 머신 이해

상태 전환을 이해하면 문제 해결에 도움이 됩니다:

Init → Drafting → Openspecing → Reviewing → Executing → ExecutionCompleted → Completed → Archived

• Openspecing: 계획 생성 중
• Reviewing: 검토 중 (산출물을 반복적으로 수정 가능)
• Executing: 실행 중 (tasks.md 적용)

상태 머신은 결국 규칙의 집합입니다. 규칙은 때로 성가시지만, 더 자주는 유용합니다. “규칙 없이는 아무것도 제대로 이룰 수 없다”는 말이 있습니다.

결론

OpenSpec 워크플로우를 통해 HagiCode 프로젝트는 AI 환각 문제를 해결하는 데 상당한 성과를 거두었습니다:

1. 환각 감소 - AI는 임의로 코드를 생성하는 대신 구조화된 사양을 따라야 합니다
2. 더 높은 품질 - 다중 계층 검증이 변경이 프로젝트 표준을 준수하도록 보장합니다
3. 더 빠른 협업 - 보관된 변경이 향후 개발에 참고 자료를 제공합니다
4. 추적 가능성 - 모든 변경에 제안, 설계, 사양, 작업의 완전한 기록이 있습니다

이 접근 방식은 AI를 더 똑똘하게 만드는 것이 아닙니다. AI를 “사양”이라는 우리 안에 넣는 것입니다. 실무는 쇠사슬 속에서 춤추는 것이 실제로 더 나은 공연으로 이어질 수 있음을 보여주었습니다.

원리는 간단합니다. 제약이 반드시 나쁜 것은 아닙니다. 글을 쓰는 것과 같습니다. 따를 형식이 있으면 종종 더 좋은 작품을 만들기 쉽습니다. 많은 사람이 제약을 싫어하는데 제약이 창의성을 제한한다고 생각하지만, 창의성도 자랄 수 있는 올바른 토양이 필요합니다.

AI 코딩 어시스턴트를 사용 중이시고 비슷한 문제에 직면하셨다면 OpenSpec을 사용해 보십시오. 사양 기반 개발은 추가 단계처럼 보일 수 있지만, 그 초기 투자는 코드 품질과 유지보수 효율에서 여러 배로 상환됩니다.

때로는 조금 늦추는 것이 실제로 가장 빠른 전진 방법입니다. 많은 사람이 아직 그것을 깨닫지 못했을 뿐입니다.

참고 자료

• OpenSpec npm 패키지: www.npmjs.com/package/@fission-ai/openspec
• HagiCode 프로젝트 저장소: github.com/HagiCode-org/site
• HagiCode 공식 웹사이트: hagicode.com
• 30분 실전 데모 시청: www.bilibili.com/video/BV1pirZBuEzq/
• Docker Compose 원클릭 설치: docs.hagicode.com/installation/docker-compose
• Desktop 빠른 설치: hagicode.com/desktop/

---

이 글이 도움이 되셨다면 GitHub에서 Star를 눌러주시면 감사하겠습니다. HagiCode 퍼블릭 베타가 이미 시작되었으며, 지금 설치하여 체험하실 수 있습니다.

---

이 글은 이 정도로 충분합니다. 특별히 심오한 것은 없으며, 몇 가지 실무 교훈의 요약일 뿐입니다. 모두에게 도움이 되기를 바랍니다. 공유는 좋은 일입니다. 본인도 무언가를 배우고, 다른 사람도 무언가를 배우게 됩니다.

그래도 글은 글일 뿐입니다. 실천이 진정으로 중요합니다. 책장에서 얻은 지식은 항상 얕은 것처럼 느껴지며, 직접 적용해야 비로 깊이 이해됩니다.

저작권 안내

읽어주셔서 감사합니다. 이 글이 유용했다면 좋아요, 북마크, 공유 부탁드립니다. 이 콘텐츠는 AI 보조 협업으로 작성되었으며, 최종 콘텐츠는 작성자에 의해 검토 및 승인되었습니다.

• 작성자: newbe36524
• 원문 링크: https://docs.hagicode.com/blog/2026-04-02-ai-coding-assistant-hallucination-openspec-spec-driven-development/
• 저작권: 별도의 명시가 없는 한 이 블로그의 모든 게시물은 BY-NC-SA 라이선스를 따릅니다. 전재 시 출처를 밝혀주세요.

태그:

• AI coding
• OpenSpec
• Specification-driven development
• HagiCode
• Development workflow

Hermes 설치 및 사용 방법: 로컬 CLI부터 Feishu 통합까지의 빠른 시작