andrewstellman/quality-playbook

버전 (Version): 1.5.6 | 저자 (Author): Andrew Stellman | 라이선스 (License): Apache 2.0

대부분의 AI 코드 리뷰 (AI code review)는 구조적 문제, 즉 null 역참조 (null dereferences), 리소스 누수 (resource leaks), 레이스 컨디션 (race conditions)만을 찾아낼 수 있습니다. 이는 실제 결함의 약 65%를 포착합니다. 나머지 35%는 의도 위반 (intent violations)입니다. 이는 코드가 무엇을 해야 하는지를 알아야만 발견할 수 있는 버그들입니다. 예외를 던지는 대신 조용히 null을 반환하는 함수, 첫 번째 값이 null일 때 통과되는 중복 키 체크 (duplicate-key check), 보호해야 할 분기 결정 (branch decision) 이후에 실행되는 정화 단계 (sanitization step) 등이 이에 해당합니다. 이러한 버그들은 명세 (spec)를 모르는 리뷰어에게는 올바르게 보입니다.

이 플레이북 (playbook)은 그 격차를 메웁니다. 이 도구는 코드베이스 (codebase)를 읽고, 찾을 수 있는 모든 소스(코드, 문서, 명세, 주석, 방어적 패턴, 커뮤니티 문서)로부터 동작 요구사항 (behavioral requirements)을 도출하며, 이러한 요구사항을 사용하여 리뷰를 수행합니다. 그 결과는 단순히 구조에 기반한 것이 아니라 의도 (intent)에 기반한 품질 시스템입니다. 이 문제에 대한 더 심도 있는 분석은 O'Reilly Radar의 기사 "AI Is Writing Our Code Faster Than We Can Verify It"를 참조하십시오.

프로젝트에 Quality Playbook을 설치하는 권장 방법은 사용 중인 AI 코딩 도구 (AI coding tool)가 대신 수행하도록 하는 것입니다:

이 저장소 (repo)를 다운로드하거나 클론 (clone)하세요 — 예를 들어, git clone https://github.com/andrewstellman/quality-playbook ~/quality-playbook 명령어를 사용하여 머신의 적절한 위치에 저장합니다. 이 작업은 한 번만 수행하면 됩니다. 동일한 클론을 사용하여 여러 대상 프로젝트에 플레이북을 설치할 수 있습니다. -
대상 프로젝트를 여세요 — Claude Code, Cursor, GitHub Copilot, Windsurf 또는 임의의 경로에 있는 파일을 읽고 명령을 실행할 수 있는 기타 에이전트 (agent) 등 선호하는 AI 코딩 도구에서 대상 프로젝트를 엽니다. QPB 클론이 AI 도구에 직접 열려 있을 필요는 없습니다. 에이전트가 사용자가 제공한 클론 경로에서 직접 파일을 읽습니다. -
AI에게 설치를 요청하세요. 다음과 같이 요청할 수 있습니다: "~/quality-playbook에서 이 프로젝트에 Quality Playbook을 설치해줘." AI 에이전트는 AGENTS.md를 읽습니다.

QPB 클론으로부터 어떤 AI 도구(AI tool)를 설치할지 파악한 후, python3 -m bin.install_skill --into <this-project> --ai-tool <tool> 명령어를 실행하고 결과를 보고합니다. 스킬(skill) 파일들은 해당 AI 도구의 표준 하위 디렉토리(.cursor/skills/quality-playbook/, .claude/skills/quality-playbook/, .github/skills/quality-playbook/ 또는 .continue/skills/quality-playbook/)에 저장됩니다. 에이전트는 다음의 3단계 우선순위에 따라 설치할 도구를 결정합니다: (a) 사용자가 지시한 내용 ("Cursor용으로 설치해줘"), (b) 스스로를 확신 있게 식별할 수 있는 경우의 자신의 정체성 (예: Cursor 세션 내에서 설치 중인 Cursor 에이전트 — 이 경우 사용자가 수정할 수 있도록 에이전트가 이러한 추론을 수행 중임을 알려줍니다), 또는 (c) (a)와 (b)가 모두 해당되지 않을 경우 사용자에게 질문합니다.

현재 지원되는 도구: Cursor, Claude Code, GitHub Copilot (copilot 또는 github 별칭), 그리고 Continue. 그 외의 다른 AI 코딩 도구들도 QPB 클론 경로의 파일을 읽고 셸 명령(shell commands)을 실행할 수 있다면 작동합니다. 만약 해당 도구의 표준 스킬 디렉토리가 아직 bin/install_skill.py에 의해 인식되지 않는 경우, --target <path> 플래그를 명시하여 설치할 수 있습니다.

전제 조건: Python 3.9 이상 버전이 PATH에 설정되어 있어야 합니다. 설치 프로그램은 Python 모듈(python3 -m bin.install_skill)이며, 3.9 이상을 요구하는 표준 라이브러리(standard-library) 기능을 사용합니다. python3 --version으로 확인하세요.

AI에게 맡기는 과정을 완전히 건너뛰고 싶다면, QPB 클론 내부에서 설치 프로그램을 직접 실행하십시오:

cd ~/quality-playbook
python3 -m bin.install_skill --into /path/to/your-target-project --ai-tool <cursor|claude|copilot|continue>

또는 아래 가이드의 3단계에 있는 수동 cp 레시피를 사용하여 스크립트 없이 직접 스킬 파일을 복사할 수도 있습니다.

이 README의 나머지 부분에는 플레이북을 설치하고 실행하기 위한 상세 지침 — 명령어, 프롬프트(prompts), 스크린샷을 포함한 전체 가이드가 포함되어 있습니다. 하지만 가장 쉽게 시작하는 방법은 문서를 완전히 건너뛰는 것입니다: 파일 하나를 다운로드하여 즐겨 사용하는 AI 챗봇에 업로드한 뒤, 도움을 요청하세요.

해당 파일은 ai_context/TOOLKIT.md입니다. 이 파일은 AI 어시스턴트(AI assistants)가 읽고 질문에 답할 수 있도록 설계된 형식으로, Quality Playbook에 관한 모든 것을 설명하는 단일 마크다운 (Markdown) 문서입니다.

Claude, ChatGPT, Cursor, GitHub Copilot, Gemini 등 사용 중인 어떤 AI 도구에서든 채팅을 열고, TOOLKIT.md를 첨부한 뒤 다음과 같이 말하세요:

"TOOLKIT.md를 읽어줘. 이제 너는 Quality Playbook의 전문가야."

그다음 무엇이든 물어보세요: "이걸 어떻게 설정하나요?", "Phase 3는 실제로 무엇을 하나요?", "구조적 코드 리뷰 (structural code review)가 놓치는 버그를 어떻게 찾아내나요?", "gap iteration과 adversarial iteration의 차이점은 무엇인가요?", "왜 내 실행 결과에서는 버그가 하나만 발견되었나요?" 여러분의 AI 어시스턴트가 설정, 실행, 결과 해석, 그리고 다음 실행을 개선하는 방법까지 안내해 줄 것입니다.

다음은 ChatGPT에서의 대화 예시입니다. 다른 AI 도구에서도 동일하게 작동합니다.

만약 문서를 직접 읽는 것을 선호한다면, 이 README의 나머지 부분에 더 상세한 정보가 포함되어 있습니다.

• 코드에서 버그를 찾기 위해 Quality Playbook을 사용하는 방법
• 플레이북 실행: 단계 (phases), 반복 (iterations), 그리고 매크로 (macros)
• 속도 제한 (Rate limits) 및 실행 예산 (run budgets)
• 플레이북의 결과물
• 작동 원리
• 로드맵 (Roadmap)
• 검증 (Validation)
• 자동화 스크립트 설정
• 저장소 구조 (Repository structure)
• 출력 예시
• 플레이북 개선 방법
• 컨텍스트 (Context)
• 라이선스 (License)
• 특허 고지 (Patent notice)

플레이북은 AI 코딩 도구가 스킬 (skill)로 인식하여 읽을 수 있는 디렉토리에 배치해야 하는 일련의 파일들(SKILL.md, quality_gate.py, references/, phase_prompts/, agents/, bin/citation_verifier.py)로 제공됩니다. 권장되는 방법은 AI 도구가 대신 설치하도록 하는 것입니다.

권장 사항: AI 도구가 설치하도록 하세요. 대상 저장소(repo) 내부에서 Claude Code, Cursor, GitHub Copilot 또는 다른 AI 코딩 어시스턴트와 채팅을 시작하세요. 그리고 다음과 같이 요청하세요:

"Quality Playbook 저장소의 AGENTS.md를 읽고, 설치 절차를 따라 이 프로젝트에 스킬을 설정해줘."

AI 에이전트가 AGENTS.md를 읽고, python3 -m bin.install_skill을 실행합니다.

대상에 맞서 실행하고, 구조화된 출력 (structured output)을 파싱하며, 결과를 보고합니다. 이것이 설치 경로가 설계된 기본 모드입니다.

대안: 스크립트를 직접 실행하기. 로컬 QPB 클론에서 다음을 실행하세요:

python3 -m bin.install_skill --into /path/to/target-repo --ai-tool cursor # 표준 방식: AI 도구의 이름을 지정
python3 -m bin.install_skill --into /path/to/target-repo # 마커 디렉토리(marker dir)를 통해 자동 감지
python3 -m bin.install_skill --target /path/to/install-root # 실제 설치 경로 지정
...

--ai-tool <name>

은 프로젝트에서 어떤 도구를 사용할지 알고 있을 때 호출하는 표준 방식입니다. 값으로는 cursor, claude, copilot (github의 별칭), 또는 continue가 있습니다. 스크립트는 마커 디렉토리가 존재하지 않으면 생성하며, 표준 하위 디렉토리(.cursor/skills/quality-playbook/, .claude/skills/quality-playbook/, .github/skills/quality-playbook/, 또는 .continue/skills/quality-playbook/)에 설치합니다. --into <target-repo>만 사용하는 경우 대상 내부의 마커 디렉토리에서 자동 감지를 시도하며, 이는 대상이 AI 도구에 의해 최소 한 번은 열려 있어야만 작동합니다. --target <path>는 해당 경로를 실제 설치 루트로 취급하여 스킬 파일들을 그곳에 직접 작성합니다. 이는 표준이 아닌 설치 위치를 사용하는 운영자에게 유용합니다. --target은 --into 및 --ai-tool 모두와 상호 배타적(mutually exclusive)입니다.

이미 SKILL.md를 스킬 디렉토리에 수동으로 복사했나요? 이 단계를 건너뛰세요. 아래 3단계에서 설명하는 수동 설치 경로도 계속 작동합니다. bin/install_skill.py는 기존 것을 대체하는 것이 아니라 추가적인 기능을 제공합니다.

설치 작업 내용: 스킬 파일들(SKILL.md, quality_gate.py, references/, phase_prompts/, agents/, 그리고 bin/citation_verifier.py)을 선택한 설치 위치로 복사합니다. 마지막에는 스모크 테스트 (smoke check)를 실행합니다 (quality_gate.py가 로드 가능한 Python인지, SKILL.md가 예상된 프론트매터 (frontmatter)와 함께 파싱되는지, references/exploration_patterns.md가...

loads). 구조화된 출력 (structured output)의 모든 실패를 보고합니다. 재설치 (Re-installs) 시에는 운영자가 편집한 파일을 <file>.operator-backup-<UTC-timestamp>로 보존하여, 로컬 편집 내용이 소리 없이 덮어쓰여지는 것을 방지합니다.

플레이북은 작업할 수 있는 문서화된 자료가 있을 때 더 나은 요구사항 (requirements), 더 적은 오탐 (false positives), 그리고 더 구체적인 버그 (bugs)를 생성합니다. 오직 평문 파일(Plaintext files) — .txt 및 .md 만 지원합니다. 다른 형식은 먼저 변환하십시오:

pdftotext spec.pdf spec.txt

pandoc -t plain spec.docx -o spec.txt

lynx -dump https://example.org/spec.html > spec.txt

대상 리포지토리(target repo) 내 문서 배치 위치:

reference_docs/
├── claude-chat-2026-03-15.md ← AI 채팅 로그, 설계 노트 (Tier 4 컨텍스트)
├── design-notes.md ← 탐색적 기술서 (exploratory writeups), 회고 (retrospectives)
...

최상위 reference_docs/ 는 채팅 로그, 설계 노트, 회고, 모든 탐색적 자료와 같은 Tier 4 컨텍스트를 보유합니다. 플레이북은 이를 1단계 (Phase 1)에서 배경 지식으로 읽어들이지만, 해당 내용의 인용구를 바이트 단위로 검증 (byte-verify) 하지는 않습니다.

reference_docs/cite/ 는 인용 가능한 자료 — 명세서 (specs), RFC, API 계약 (API contracts), 공개 표준 (published standards)을 보유합니다. 이곳의 모든 파일은 quality_gate.py가 바이트 단위로 검증하는 기계적 인용 발췌문 (mechanical citation excerpt)을 포함한 FORMAL_DOC 레코드를 생성합니다. 만약 BUG 또는 REQ에서 이를 인용하면, 게이트 (gate)는 인용구가 디스크 상의 바이트와 일치하는지 확인합니다. 별도의 사이드카 파일 (sidecar file), 프론트매터 헤더 (frontmatter header), 또는 어떠한 메타데이터도 필요하지 않습니다. cite/ 디렉토리에 배치하는 것 자체가 "이것은 인용 가능하다"라고 말하는 플래그 역할을 합니다. (선택 사항: cite/ 파일의 첫 번째 공백이 아닌 줄에 <!-- qpb-tier: 2 --> 또는 # qpb-tier: 2를 작성하여 Tier 2로 표시할 수 있습니다. 표시가 없으면 기본적으로 Tier 1로 간주됩니다.)

문서가 전혀 없는 경우에도 플레이북은 실행됩니다. 이 경우 소스 트리 (source tree)만으로 작동하며 (Tier 3 증거), Tier 5 추론된 요구사항 (inferred requirements)을 생성합니다. 결과는 더 약하지만 유효합니다.

reference_docs에 포함되지 않는 것:

• 이진 파일 또는 포맷된 파일 (PDF, DOCX, HTML) — 먼저 변환한 후, 평문 (plaintext)으로 커밋하세요
• 코드 발췌본 (Code excerpts) — 소스 트리 (source tree)가 이미 Tier 3 권한을 가집니다
• 테스트 픽스처 (Test fixtures) 또는 샘플 데이터 — 이것들은 프로젝트 아티팩트 (artifacts)이지, 문서가 아닙니다
• LLM이 읽어서는 안 되는 개인적이거나 민감한 모든 것 —
  reference_docs/

내용은 Phase 1 프롬프트 (prompts)에 로드됩니다.

bin/install_skill.py를 사용하는 대신 수동으로 설치하는 것을 선호한다면,

Step 1부터, 스킬 파일들을 프로젝트에 직접 복사하세요:

Claude Code:

mkdir -p .claude/skills/quality-playbook/references
mkdir -p .claude/skills/quality-playbook/phase_prompts
mkdir -p .claude/skills/quality-playbook/agents
...

GitHub Copilot (flat layout):

mkdir -p .github/skills/references
mkdir -p .github/skills/phase_prompts
mkdir -p .github/skills/agents
...

GitHub Copilot (nested layout):

mkdir -p .github/skills/quality-playbook/references
mkdir -p .github/skills/quality-playbook/phase_prompts
mkdir -p .github/skills/quality-playbook/agents
...

Cursor, Windsurf, 기타 도구: 위의 위치 중 아무 곳이나 사용하거나, 스킬 파일들 (SKILL.md, quality_gate.py, references/, phase_prompts/, agents/, 그리고 bin/citation_verifier.py)을 프로젝트 루트 (root)에 두세요. 러너 (runner), 게이트 (gate), 그리고 오케스트레이터 에이전트 (orchestrator agents)는 다음 네 곳을 모두 확인합니다 — 레포지토리 루트의 SKILL.md, Claude의 .claude/skills/quality-playbook/, 그리고 Copilot의 두 가지 레이아웃(layouts)입니다.

OpenAI Codex CLI: v1.5.3 버전에서 Claude 및 Copilot과 함께 세 번째 러너로서 독립형 Codex CLI (codex-cli 0.125+)가 추가되었습니다. 별도의 스킬 설치 레이아웃은 없으며 — Codex는 위의 위치 중 어느 곳에서든 플레이북 (playbook)을 실행합니다. bin/run_playbook.py를 통해 사용하려면 --codex를 전달하세요 (Step 4 및 아래의 "모든 것을 자율적으로 실행하기" 섹션 참조).

Claude Code:

claude --agent agents/quality-playbook.agent.md

파일 쓰기 승인 프롬프트를 건너뛰려면 --dangerously-skip-permissions를 추가하세요.

GitHub Copilot: VS Code, IntelliJ 또는 Copilot을 지원하는 모든 IDE에서 채팅 패널을 열고 다음과 같이 말하세요: "이 프로젝트에 quality playbook을 실행해줘." CLI의 경우, 프롬프트를 건너뛰려면 copilot-cli에 --yolo를 사용하세요.

OpenAI Codex CLI:

python3 -m bin.run_playbook --codex ./my-project

이 명령은 각 playbook 단계에 대해 codex exec --full-auto (--model gpt-5-codex (또는 codex 설정에 있는 다른 모델 이름)를 전달하지 않는 한, ~/.codex/config.toml에서 모델을 선택하는 sandboxed automatic execution (codex 버전의 gh copilot --yolo에 해당함)를 호출합니다.

Cursor: Composer (Cmd+I / Ctrl+I)를 열고 다음과 같이 말하세요: "SKILL.md를 읽고 이 프로젝트에 quality playbook을 실행해줘."

Windsurf: Cascade를 열고 다음과 같이 말하세요: "SKILL.md를 읽고 이 프로젝트에 quality playbook을 실행해줘."

Playbook은 6단계로 실행됩니다. 각 단계는 고유한 컨텍스트 윈도우 (context window)를 가집니다. 이것이 대규모 코드베이스에서 컨텍스트 부족 현상 없이 심층 분석 (deep analysis)을 수행할 수 있게 해주는 핵심입니다. 각 단계가 끝난 후에는 "계속해줘 (keep going)"라고 말하여 진행하세요.