1. 시작하기 (Getting Started)
"Models change. Sessions end. Projects survive. (AI 모델은 계속 달라지고 세션은 끝나지만, 프로젝트는 Git 문서로 보존됩니다.)"
Q1. 왜 REPL Works를 만들었나요?
AI는 코드를 매우 빠르게 작성하지만, 프로젝트의 이전 맥락과 의사결정 이유(Project Memory)를 스스로 기억하지 못합니다. 세션이 끊기거나 새로운 AI 모델을 도입할 때마다 다음과 같은 내용을 반복해서 다시 설명해야 하는 비효율이 발생합니다:
- Why: 왜 이 제품을 만들고 있는가? (핵심 비즈니스 목적)
- What: 어떤 기술 아키텍처 및 구현 규칙 결정을 내렸는가?
- Status: 현재 어느 태스크까지 완성되었고 어디부터 이어서 구현해야 하는가?
REPL Works는 프로젝트 기억을 대화창이 아닌 Git에 마크다운 문서 자산으로 보존함으로써 세션과 모델이 바뀌어도 100% 지속성을 유지하기 위해 탄생했습니다.
Q2. REPL Works는 정확히 무엇인가요?
REPL Works는 AI Issue Publisher와 REPL CLI 같은 전용 CLI 도구를 제공하지만, 단순한 소프트웨어 도구에 국한되지 않습니다.
REPL Works는 **인간 엔지니어와 AI가 장기간 프로젝트를 지속 가능하게 운영하기 위한 AI-Native 프로덕트 개발 방법론(Framework)**입니다.
문서 헌법, Git 커밋 규칙, 4단계 파이프라인(Discussion → Document → Execution → Human Review)을 통해 개발 속도를 높이고 세션 비용을 극대화 절감합니다.
Q3. 일반 AI Agent와 REPL Works의 차이점은 무엇인가요?
| 비교 항목 | 일반 AI Agent (Action Focus) | REPL Works (Memory & Workflow) |
|---|---|---|
| 핵심 목적 | 일회성 작업 및 코드 자동 생성 | 프로젝트 수명 주기 지속성 및 의도 유지 |
| 기억 저장 위치 | 일시적 대화 세션, Vector DB, 런타임 | Git 저장소 + Markdown 6+1종 표준 문서 |
| 모델 의존성 | 높음 (특정 LLM 맥락에 강하게 의존) | 매우 낮음 (문서 기반 모델 독립성 확보) |
| 모델 변경 시 | 프롬프트 재설정 및 세션 재구성 필요 | 마크다운 명세서 읽기로 즉각 복원 가능 |
| 핵심 질문 | “지금 어떤 코드를 작성할까?” | “왜 이 프로덕트를 만들고 어떻게 유지할까?” |
| 결과물 | 단발성 코드 / 스크립트 | 지속 가능한 프로덕트 자산 및 명세 헌법 |
AI Agent와 REPL Works는 경쟁 관계가 아닙니다. AI Agent(코딩형 AI)가 올바른 수락 조건(Acceptance Criteria) 범위 내에서 단일 커밋을 완수하도록 통제해 주는 가이드라인이 REPL Works입니다.
Q4. REPL Works 호환 프로젝트란 무엇인가요?
REPL Works 호환 프로젝트는 프로젝트 기억을 대화가 아니라 Git의 문서(PRODUCT_SPEC.md, TECH_STACK.md, ARCHITECTURE.md, TASKS.md, AGENTS.md)로 관리하는 프로젝트입니다.
이 프로젝트는 REPL Works 방식을 따라 문서를 유지하고, 그 문서를 기준으로 AI와 사람이 작업합니다.
Q5. ChatGPT나 Claude 대화창만으로 개발하면 안 되나요?
단일 대화창으로 1회성 프로토타입을 만드는 것은 가능합니다. 그러나 프로젝트 규모가 커지고 기능이 추가될수록 동일한 프로젝트 맥락을 매번 재설명해야 하는 비용 폭발이 일어납니다.
REPL Works는 ChatGPT/Gemini 같은 대화형 AI(기획 및 명세 작성)와 Claude Code/Codex 같은 코딩형 AI(명세 기반 단일 커밋 구현)를 엄격히 분리합니다. 대화 이력 대신 정제된 문서 자산을 통해 반복 설명을 없애줍니다.
2. 핵심 작동 방식 (How It Works)
Q6. 왜 대화 이력(Chat History) 대신 Git과 문서를 사용하나요?
채팅 대화 이력은 일시적인 커뮤니케이션 수단에 불과합니다. 수개월 동안 유지 관리되는 실제 프로덕트에서는 다음 한계가 명확합니다:
- 세션 휘발성: 세션이 닫히거나 맥락 길이를 초과하면 이전 의사결정 배경이 소멸함.
- 환각 유발: 길어진 대화 맥락은 에이전트의 환각(Hallucination) 및 오버 스코프 구현을 유발함.
REPL Works는 Git 커밋 및 마크다운 명세서를 **단일 진실 출처(Single Source of Truth)**로 격상시켜, 모든 세션이 동일한 기억 위에서 시작되도록 보장합니다.
Q7. 왜 GitHub Issue 및 Pull Request 절차를 따르나요?
검증되지 않은 에이전트의 코드 생성을 메인 브랜치에 직접 적용하면 코드베이스가 쉽게 오염됩니다.
REPL Works 파이프라인에서는:
- 대화형 AI가 검증 가능한 수락 조건이 명시된 GitHub Issue 생성 (또는
ai-issue사용) - 코딩형 AI가 1-Task 1-Commit 범위 내에서 작업 후 Pull Request 작성
- Human Reviewer가 빌드 및 유닛/E2E 테스트 수행 후 최종 Merge 승인
이 과정을 통해 품질과 안전성을 완벽히 확보합니다.
Q8. 왜 6종 표준 문서로 역할을 분리했나요?
단일 거대 문서나 무질서한 파편화 문서는 AI와 사람 모두에게 혼란을 줍니다. REPL Works는 수많은 개발 문서를 AI가 가장 잘 이해하는 6+1종 표준 명세 헌법으로 정량화했습니다:
IDEAS.md: 왜 이 아이디어가 가치 있는가? (Human 주도 작성)
PITCHING_SCRIPT.md: 이 프로덕트를 어떻게 전달할 것인가? (Human 주도 작성)
PRODUCT_SPEC.md: 무엇을 만들고 어떤 수락 기준을 만족해야 하는가?
TECH_STACK.md: 어떤 기술 스택과 구현 제약 조건을 따를 것인가?
ARCHITECTURE.md: 시스템 모듈과 데이터 흐름은 어떻게 구성되는가?
TASKS.md: 지금 당장 실행해야 할 단위 태스크 마일스톤은 무엇인가?
AGENTS.md: AI 에이전트는 어떤 규칙과 경계 조건 내에서 작업해야 하는가?
Q9. 왜 대화형 AI와 코딩형 AI를 엄격히 분리하나요?
두 에이전트 역할을 분리하는 가장 큰 목적은 1) AI 환각 현상 원천 차단 및 2) 토큰 비용 최적화입니다.
- 대화형 AI: 제품 요구사항 정의, 아키텍처 토론, 고품질 문서 수립 담당
- 코딩형 AI: 승인된
AGENTS.md헌법과TASKS.md의 단일 태스크만을 읽고 정밀 구현 담당
구현 에이전트에게 전체 대화 이력을 주지 않고 authoritative 문서만 전달하므로 환각 및 오버 스코프를 완전히 막을 수 있습니다.
3. 아키텍처 & 원칙 (Architecture & Principles)
Q10. PRODUCT_SPEC.md는 왜 필요한가요?
PRODUCT_SPEC.md는 기획, 비즈니스, UI/UX 수락 기준을 통합한 제품 요구사항 기준 문서입니다.
이 문서는 다음 4가지 핵심 질문에 명확히 답할 수 있어야 합니다:
- What the product is: 이 프로덕트는 무엇인가?
- What the product does: 이 프로덕트가 수행하는 핵심 가치는 무엇인가?
- What the user can do: 사용자가 실행할 수 있는 작업 범위는 무엇인가?
- What success means: 작업 성공과 수락 기준(Acceptance Criteria)은 무엇인가?
Q11. REPL Works는 어떻게 토큰 및 컨텍스트 비용을 절감하나요?
일반적인 대화형 AI 개발에서는 대화가 길어질수록 10만~20만 토큰의 거대한 컨텍스트를 매 프롬프트마다 재전송해야 합니다.
REPL Works는 핵심 명세를 Git 마크다운 문서로 압축 관리하므로, 코딩형 AI는 작업 시 필요한 문항만을 읽어 프롬프트 입력 토큰 소비량을 최소 70% 이상 절감합니다.
Q12. 특정 AI 모델이나 개발 기술 스택에 종속되나요?
종속되지 않습니다. REPL Works의 핵심 원칙 중 하나는 **모델 독립성(Model Independence)**입니다.
프로젝트 기억이 특정 LLM이나 플랫폼이 아닌 오픈 표준 마크다운 형식으로 Git에 보존되므로, 다음과 같은 다양한 기술 스택 및 AI 모델에서 100% 동일하게 동작합니다:
- 프레임워크: Astro, React, Node.js, Go, Python, Laravel 등
- AI 모델: Claude 3.5 Sonnet, GPT-4o, Gemini 1.5 Pro, DeepSeek, Local Ollama 등
4. 요약 (Summary)
AI 모델은 바뀝니다.
채팅 세션도 끝납니다.
프로젝트는 계속되어야 합니다.