EN 한국어 日本語 中文
처음이라면 · INTRO 전체 구조 · REFERENCE →
QE FRAMEWORK · 5분 가이드

AI에게 제대로 된 일을 시키는 프레임워크

v6.5.0 신규 · Contract Layer — AI가 비즈니스 로직을 몰래 훼손하는 것을 기계적으로 차단하는 계약 기반 검증 레이어. 자세한 내용은 아래 용어집 + 전체 가이드.

QE Framework는 AI에게 코딩 일을 시킬 때 스펙·실행·검증을 자동으로 끼워 넣어, "대충 했네" 또는 "엉뚱한 걸 만들었네"를 시스템 레벨에서 막아줍니다.

0130초 피치

왜 필요한가. AI에게 "이거 고쳐줘"라고 말하면 대개 세 가지 중 하나가 깨집니다 — 요청이 모호해서 AI가 추측하거나, 실행은 했는데 뭘 했는지 추적이 안 되거나, "다 됐어요"라고 하는데 실제론 반쯤만 된 상태. 인간 개발자 사이에서도 이 문제를 막기 위해 Spec → 구현 → 리뷰를 거칩니다. QE는 AI에게 같은 규율을 강제합니다.

어떻게 다른가. 단순한 프롬프트 모음이 아닙니다. 모든 작업이 TASK_REQUEST(무엇을 할지)와 VERIFY_CHECKLIST(어떻게 확인할지) 두 개 파일로 먼저 남습니다. 실행은 그 후에 일어나고, 각 체크리스트 항목이 yes/no로 판정된 뒤에만 "완료"가 됩니다. 중간에 실패하면 자동으로 재시도 사양이 생성됩니다.

무엇이 보장되는가. (1) 사용자는 AI가 뭘 할 계획인지 실행 전에 봅니다. (2) AI는 자기 결과를 스스로 채점하지 않습니다 — 별도 검증·감독 단계가 있습니다. (3) 어떤 단계든 Claude 또는 Codex로 바꿔 끼울 수 있고, 외부 API를 직접 호출하지 않으므로 의존성이 격리됩니다.

025초 비유

QE를 이해하는 가장 빠른 방법 — 작업실(studio)로 상상하세요.

SKILL
도구
망치·드릴 같은 기능
AGENT
직원
도구를 실제로 쓰는 사람
HOOK
규칙
"톱질 전엔 고글" 같은 자동 게이트
SPEC
계약서
무엇을 만들지 적힌 문서

03처음이면 이 4가지만 하세요

  1. /Qinit — 프로젝트에 프레임워크 설치 (CLAUDE.md, .qe/ 디렉토리 자동 생성)
  2. /Qplan "하고 싶은 일 한 줄" — AI가 로드맵과 단계를 제안합니다
  3. /Qgs Phase 1: 짧은이름 — 구체적 스펙 문서 2개가 생성됩니다 (승인하면 바로 실행)
  4. 끝. 이후 검증·감독은 자동 — 실패하면 AI가 스스로 재시도하고 완료되면 알려줍니다.
# 나머지 명령들은 이 4개가 익숙해진 다음에 배워도 됩니다.
💡 항상 /Qplan부터 써도 됩니다. Qplan이 작업 규모를 자동 판정해서, 간단한 일(버그 하나·작은 리팩터)로 판단되면 로드맵 없이 /Qgs Fix: …로 바로 넘어갑니다. 규모 판단은 사용자가 안 해도 됩니다 — Qplan이 Micro / Small / Full로 나눠 알아서 경로를 잡습니다.

04실제로 이렇게 흘러갑니다

사용자: "로그인 버튼 눌러도 반응 없는 버그 고쳐줘"
1

계획 (Plan)

/Qplan이 작업 규모를 판단 — "버그 하나니까 Micro 스케일"로 잡고 1줄 플랜을 제안합니다. 로드맵·단계 없이 바로 다음으로 넘어갑니다.

2

스펙 생성 (Spec)

/Qgs가 TASK_REQUEST(어느 파일의 어떤 함수를 어떻게 고칠지)와 VERIFY_CHECKLIST(고친 뒤 무엇을 확인할지)를 만듭니다. 사용자는 이 두 파일만 슥 보고 "맞아, 이대로 해" 하고 승인.

3

실행 (Execute)

/Qatomic-run이 체크리스트를 병렬 실행. 파일이 여러 개면 여러 명의 AI 직원(Haiku)이 동시에 나눠 수정합니다. Hook이 매번 "제대로 쓰고 있나?" 자동 확인.

4

검증 (Verify)

/Qcode-run-task가 테스트를 돌리고 VERIFY_CHECKLIST를 하나씩 확인. 하나라도 실패하면 자동으로 수정 → 재실행 → 재검증 (최대 3번). 통과하면 "완료" 보고.

05핵심 용어 15개

전체 Reference를 읽기 전에 알고 있으면 좋은 단어들.

PSE Chain
사용자 워크플로우 4단계 (Plan → Spec → Execute → Verify). 모든 작업의 뼈대.
SIVS Loop
품질 게이트 4단계 (Spec → Implement → Verify → Supervise). PSE 안에서 돌아가는 내부 검증.
Skill
AI가 특정 상황에 호출할 수 있는 기능 단위. /Qplan 같은 슬래시 명령.
Agent
스킬이 위임하는 실행 주체 (E* 접두사). 백그라운드에서 일하는 AI 직원.
Hook
이벤트 기반 자동 게이트. AI가 무엇을 하기 전/후에 결정론적으로 작동하는 규칙.
Spec
작업의 계약서. TASK_REQUEST와 VERIFY_CHECKLIST 두 파일로 표현됨.
TASK_REQUEST
"무엇을 할지" 명세 — 체크리스트 + 의존성 + 출력 파일 경로.
VERIFY_CHECKLIST
"어떻게 완료를 확인할지" — yes/no로 답할 수 있는 판정 항목 목록.
Wave
병렬 실행 단위. 의존성 없는 작업들을 한꺼번에 여러 AI에게 분배.
Teammate
Wave 안에서 일하는 Haiku 모델 에이전트. 빠르고 값싸고 반복적인 일 담당.
Verify
"했나?" 확인 — 객관적 yes/no 판정.
Supervise
"잘 했나?" 평가 — 보안·품질·문서 등 전문가 관점 평가. Verify와 다름.
Context Memory
폴더별로 분할된 AI 컨텍스트. 현재 작업 디렉토리에 맞는 것만 로드해 토큰 절약.
Phase
로드맵의 한 단계. 여러 Wave를 포함할 수 있음. Phase 1, Phase 2, …
Handoff
스킬이 끝날 때 다음 명령을 알려주는 표준 블록. 사용자가 복붙할 수 있도록 짧게.
⚠️ Qutopia Mode
모든 스킬이 확인 프롬프트를 건너뛰고 첫 번째 옵션을 자동 선택하도록 만드는 자율 실행 스위치. 빠르지만 잘못된 파일을 커밋하거나 main에 push하거나 파괴적 단계를 연쇄 실행할 수 있음. 요구사항이 명확하고, 모든 단계가 되돌릴 수 있고, 독립된 feature branch일 때에만 활성화. 전체 사전 체크리스트는 USAGE_GUIDE §10 참조. 세션 종료 전 반드시 /Qutopia off 실행.
Contract Layer (v6.5+)
비즈니스 로직을 구조화된 markdown 계약(6섹션: Signature / Purpose / Constraints / Flow / Invariants / Error Modes)으로 고정하고, LLM judge가 계약·구현·테스트 3자를 대조해 일치 여부를 판정하는 검증 레이어. AI 리팩토링이 의도를 몰래 훼손하는 "바이브 코딩"을 기계적으로 차단. /Qcontract와 /Qverify-contract로 사용.
/Qcontract
계약 생애주기 관리 스킬. create / edit / list / approve 서브커맨드로 .qe/contracts/active/의 계약을 작성·갱신·승인. 승인은 대화형 게이트(AskUserQuestion) + .qe/contracts/.lock 해시 기록 2층 방어.
/Qverify-contract
LLM judge(Econtract-judge 에이전트) 기반 계약 준수 검증 스킬. 3-해시(contract / impl / test) 캐시로 같은 내용 재판정 방지. 단일 계약(<name>) 또는 전체(--all) 모드 지원. /Qcode-run-task Step 4.10에서 자동 호출.