본문으로 건너뛰기
REPL WorksREPL Works
Menu

WORKFLOW GUIDE

워크플로우 가이드

REPL Works 방법론으로 아이디어에서 배포와 운영까지 진행하는 순서를, 실제 오픈소스 프로젝트 ai-issue를 따라가며 설명합니다.

다른 문서를 열지 않고 이 문서만 읽어도 따라 할 수 있도록 썼습니다.

설명은 실제 프로젝트 하나를 따라가며 진행합니다. ai-issue는 AI 대화에서 나온 마크다운을 GitHub 이슈로 바꿔 주는 CLI 도구로, REPL Works 방식으로 만들어 배포했고 오픈소스입니다. 문서와 커밋을 모두 직접 열어 확인할 수 있고, brew install replworks/tap/ai-issue로 설치해서 결과물도 써 볼 수 있습니다.

전체 흐름은 다음과 같습니다.

대화형 AI + 사람 → 문서 6종 → 코딩형 AI → 빌드·린트·테스트 → 사람의 검토·커밋 → 운영

사람과 대화형 AI가 아이디어를 문서로 굳히고, 코딩형 AI가 그 문서를 읽고 TASK 하나씩 구현하며, 사람이 변경분을 검토해 커밋합니다. 제품이 나간 뒤 들어오는 요구도 같은 문서에서 다시 시작합니다.

1. 왜 문서로 기억을 남기는가

AI로 개발하는 프로젝트는 대개 중반 이후 같은 벽에 부딪힙니다. 채팅이 길어지면 AI가 앞에서 정한 설계와 컨벤션을 잊고 그럴듯한 오답을 만들어 냅니다. 모델이나 도구를 바꾸면 맥락이 끊겨서 처음부터 다시 설명해야 합니다. 세션이 끝나면 프로젝트가 왜 이렇게 생겼는지 남은 기록이 없습니다.

원인은 하나입니다. 프로젝트의 기억이 채팅 세션 안에 있기 때문입니다. 세션은 길어지면 흐려지고, 닫히면 사라집니다. REPL Works는 기억을 두 종류로 나눕니다.

세션 기억(Session Memory)은 대화창과 AI 런타임에 있는 휘발성 맥락입니다. 사라져도 되는 것만 여기에 둡니다. 프로젝트 기억(Project Memory)은 Git 저장소 안의 마크다운 문서입니다. 결정과 설계와 작업 계획은 전부 여기에 있고, 세션이 끝나도 어떤 모델이든 이 문서를 읽으면 이어서 개발할 수 있습니다.

그래서 이 방식에서 AI에게 하는 일은 대화가 아니라 문서를 읽고 쓰게 하는 것입니다. 이 문서의 나머지는 그 문서가 무엇이고 누가 언제 쓰는지에 대한 설명입니다.

2. 준비: 저장소 구조와 AGENTS.md

REPL Works 프로젝트의 저장소에는 문서 6종과 공통 규칙 파일 하나가 있습니다. ai-issue의 구조입니다.

.
├── AGENTS.md # 공통 규칙. 고정, 수정 금지
└── .replworks/
├── docs/
│ ├── IDEAS.md # 1단계: 사람을 위한 문서
│ └── PITCHING_SCRIPT.md
├── PRODUCT_SPEC.md # 2단계: AI를 위한 문서
├── TECH_STACK.md
├── ARCHITECTURE.md
└── TASKS.md

.replworks/docs/의 두 문서는 사람이 읽는 문서이고, 나머지 네 문서는 AI가 구현의 기준으로 읽는 문서입니다. 이 구분은 관례가 아니라 AGENTS.md가 강제하는 규칙입니다. AGENTS.md의 앞부분이 AI가 읽을 문서와 순서를 정합니다.

## DOCUMENT_ORDER
1. AGENTS.md
2. .replworks/PRODUCT_SPEC.md
3. .replworks/TECH_STACK.md
4. .replworks/ARCHITECTURE.md
5. .replworks/TASKS.md
Only these documents are authoritative.
## IGNORE
Ignore all files under:
.replworks/docs/
Never use files in .replworks/docs/ as requirements.
Never implement features described only in .replworks/docs/.

IDEAS.md는 아이디어를 잃어버리지 않기 위한 문서이지 요구사항이 아닙니다. 그래서 AI는 이 폴더를 읽지 않고, 여기에만 적힌 기능을 구현하지도 않습니다. 반대로 네 문서끼리 내용이 충돌하면 우선순위가 정해져 있습니다.

PRODUCT_SPEC.md > TECH_STACK.md > ARCHITECTURE.md > TASKS.md > everything else

무엇을 만드는지가 어떻게 만드는지보다, 어떻게 만드는지가 무엇을 먼저 할지보다 우선한다는 뜻입니다. 각 문서가 답하는 질문은 하나씩입니다. PRODUCT_SPEC.md는 제품이 무엇이고 무엇을 하는지, TECH_STACK.md는 어떤 기술 규칙으로 구현하는지, ARCHITECTURE.md는 시스템이 어떻게 구성되는지, TASKS.md는 다음에 무엇을 구현하는지를 정의합니다. AGENTS.md는 문서끼리 책임을 옮기지 말라고 명시합니다.

AGENTS.md는 REPL Works가 미리 정의한 공통 규칙입니다. 프로젝트마다 새로 쓰거나 고치지 않고 그대로 복사해 둡니다. AI도 사람도 이 파일을 수정하지 않습니다. 원본은 GitHub 저장소에서 받을 수 있습니다.

여기까지 하면 새 저장소의 루트에 AGENTS.md가 있고, .replworks/docs/ 폴더가 만들어져 있어야 합니다.

3. 기획·설계

문서 6종은 두 묶음으로, 순서대로 대화형 AI와 사람이 함께 씁니다. 1단계는 사람을 위한 문서이고 ChatGPT를 추천합니다. 2단계는 AI를 위한 문서이고 Claude를 추천합니다. 어떤 도구를 쓰든 방식은 같습니다. 먼저 대화로 생각을 정리하고, 정리가 끝나면 문서 생성 프롬프트를 붙여 넣어 결과를 파일로 저장합니다.

3.1 아이디어를 기록한다: IDEAS.md

처음에는 만들고 싶은 것을 대화형 AI와 자유롭게 이야기합니다. 누구를 위한 제품인지, 기존 해결책과 무엇이 다른지, 사용자가 계속 쓸 이유가 있는지, 사업적으로나 기술적으로 이어 갈 수 있는지를 다룹니다. 대화가 충분히 정리되면 같은 대화 안에서 아래 프롬프트를 실행합니다.

IDEA_GENERATION_PROMPT.txt
Generate IDEAS.md from this conversation.
Purpose: a document the author reads to decide "do we build this or not", and to recall months later what the idea is and why it came up. The human decides; this document provides the material. Write concise Korean, using the author's own terms. It does not need to be exhaustive or formally precise.
Rules:
- Use only what was said in this conversation. Do not fill gaps.
- The idea is what the user stated or accepted. AI suggestions the user did not accept are not part of the idea.
- Do not add your own evaluation of the idea or a go/no-go recommendation. Evidence, objections, and scores that appeared in the conversation are copied as they appeared, with their tags ([출처]/[추론]/[의견]) if they had one. Do not invent numbers.
- Keep existence evidence (someone is doing it) separate from demand evidence (someone is dissatisfied or pays).
Top of the document:
- 한 줄 요약
- 결정 준비도: "판단 가능" or "더 논의 필요", with a one-line reason. This assesses whether the conversation covers enough to decide, not whether the idea is good.
Sections (omit any that were not discussed):
1. 발단: what triggered the idea, what was seen or experienced, by whom
2. 문제와 대상 사용자
3. 아이디어: what it does, as stated
4. 기존 대안
5. 증거: 존재 증거 / 수요 증거 / 반증
6. 반론과 의문, and whether each was resolved
7. 성공 조건(가정)과 한국 조건, if discussed. Put "fatal + unverified" items first.
8. 검증 결과: only if a score or table was made in the conversation, copied as is. Otherwise "검증 미실시".
9. 논의 중 바뀐 점 / 기각된 방향
10. 빠진 것과 미해결 질문: using this checklist as a guide, list which items are missing or only thinly discussed: 발단, 문제, 대상 사용자, 기존 대안, 수요 증거, 반증, 첫 사용자 확보, 누가 돈을 내는가, 한국 조건, 플랫폼·법규 의존, 단위 경제, 비어 있는 이유, 가장 그럴듯한 실패 이유. For each, one question to discuss next. Questions only, no answers.

이 프롬프트는 의도적으로 AI가 아이디어를 개선하지 못하게 막습니다. 이 단계의 목적은 좋은 아이디어를 만드는 것이 아니라 대화에서 나온 아이디어를 그대로 보존하는 것입니다. 결과는 .replworks/docs/IDEAS.md로 저장합니다. 발표나 설명에 쓸 PITCHING_SCRIPT.md도 같은 방식으로 만들며, 프롬프트는 프롬프트 페이지에 있습니다.

3.2 제품을 정의한다: PRODUCT_SPEC.md

두 번째 문서부터는 AI가 구현의 기준으로 읽습니다. PRODUCT_SPEC.md는 제품이 무엇이고 무엇을 하는지만 정의하는 최상위 문서입니다. 구현 방법은 여기에 쓰지 않습니다. 이 점을 프롬프트가 강하게 제한합니다.

PRODUCT_SPECIFICATION_PROMPT.txt
Generate PRODUCT_SPEC.md.
INPUT
- The product information provided with this request.
Product discovery and idea validation are complete and final.
It is the only source of product information.
- If wireframes or mockups are provided, translate their structure into text.
MUST NOT reference or embed image files.
- MUST NOT create any other document.
- Output the contents of PRODUCT_SPEC.md only.
STOP CONDITIONS
If information required for any section is missing, ambiguous, or contradictory:
output ONLY a numbered list of questions. Nothing else.
After I answer, treat my answers as final input and continue.
MUST NOT invent information to fill a gap.
PURPOSE
The purpose of PRODUCT_SPEC.md is to define:
What the product is.
What the product does.
How it works from the end user's perspective, including its UI and UX.
What the user can do.
SCOPE BOUNDARY
- Specify only what the end user can observe and do.
- Specify only what is to be built now. Features that were discussed but
deferred to later MUST NOT appear in the document, except as
Non-Goals if explicitly excluded.
- UI and UX are product behavior. MUST specify them (see USER INTERFACE RULES).
- How the product works internally (mechanism) belongs to ARCHITECTURE.md.
MUST NOT describe implementation, architecture, technologies, tech stacks,
programming languages, databases, internal APIs, internal components,
or directory structures.
- Persistence is specified as observable behavior (what is kept across sessions),
never as storage technology.
- Human-owned. MUST NOT specify:
wording, copy, translations, images,
visual styling (colors, typography, spacing, visual polish).
Specify which content slots exist and what each is for, not their content.
- Business outcomes (revenue, user counts, conversion, growth, market targets)
are out of scope. MUST NOT include them anywhere in the document.
- MUST NOT propose improvements.
- MUST NOT add features that were not discussed.
- MUST NOT expand the scope.
USER INTERFACE RULES
For every surface the user interacts with:
- Screens: give each a stable ID (SCR-001, ...), its purpose, and the elements on it.
- Elements: for each, its purpose and what the user can do with it.
- Arrangement: relative placement, grouping, and hierarchy only.
MUST NOT specify exact sizes, spacing, or visual styling.
- States: every state that applies (initial, empty, loading, populated, error,
disabled) and what is shown in each.
- Navigation: for each trigger, the destination.
- Interactions: for each user action, the observable result.
- Platform or window-size differences, only if stated in the input.
For non-graphical products (e.g. command-line):
- Every command, option, input, and the structure of output that users
or other programs rely on, and exit behavior.
MUST NOT specify exact output wording unless programs depend on it.
REQUIREMENT RULES
- Give every Functional Requirement a stable ID (FR-001, FR-002, ...).
- Each requirement is one externally observable behavior that can be
verified pass/fail. If it cannot be written objectively, ask.
- Product Goals: only what the product enables the end user to do.
MUST NOT include business outcomes.
- Error Conditions specify the observable behavior for each condition.
- Acceptance Criteria reference requirement and screen IDs and are pass/fail verifiable.
- Non-Goals: only what the input explicitly excludes.
- External Systems: list each external system the product depends on
and the behavior relied on.
Mark with [UNVERIFIED] the heading of any section whose behavior depends on
an external system whose behavior has not been observed.
- Constraints: only observable non-functional requirements stated in the input
(supported platforms or environments, performance, offline behavior,
data retention, accessibility). If none are stated, write "None stated."
The document must include, in this order:
- Purpose
- Problem
- Product Goals
- Users
- Inputs
- Outputs
- Constraints
- External Systems
- User Interface
- Functional Requirements
- User Flows
- Error Conditions
- Non-Goals
- Acceptance Criteria
FORMAT
LANGUAGE
- Write the entire document in English, regardless of the input language.
Translate all input content into English.
- Exception: proper nouns and identifiers stay as given.
- Content slots are specified by purpose only (see SCOPE BOUNDARY),
so this rule never requires writing product copy.
READER
- The only reader is a coding AI agent. There is no human reader.
- Optimize for unambiguous, direct implementation and test derivation.
- Every line MUST be an actionable, verifiable statement or a defined fact.
STYLE
- MUST NOT include background, rationale, motivation, narrative,
introductions, summaries, transitions, or commentary.
- One behavior or fact per bullet. MUST NOT combine multiple behaviors
in one bullet.
- Use only "MUST" and "MUST NOT" for requirements.
MUST NOT use "should", "may", "can", "ideally", "preferably".
- MUST NOT use vague terms: "etc.", "and so on", "appropriate", "as needed",
"fast", "user-friendly", "properly", "similar".
Enumerate every item explicitly. If it cannot be enumerated, ask.
- Use one term per concept. Define it once in the section where it
first appears and reuse it exactly. MUST NOT use synonyms.
- Reference other items by ID only (FR-xxx, SCR-xxx, EL-xxx, ERR-xxx).
MUST NOT refer to them by description.
STRUCTURE
- Flat bullets. Maximum nesting depth: 2.
- Per screen, use this fixed schema in this order:
ID / Purpose / Elements (EL-xxx: purpose, user actions) /
States / Navigation (trigger -> destination) /
Interactions (action -> observable result)
- Use "trigger -> result" lines for navigation and interactions.
- Give IDs to every element (EL-), error condition (ERR-),
and acceptance criterion (AC-).
- No emphasis styling, no emoji, no ASCII art, no images.
- Output the document only.

IDEAS.md를 만들었던 대화에 이어서 실행해도 되고, IDEAS.md를 붙여 넣은 새 대화에서 실행해도 됩니다. 결과는 .replworks/PRODUCT_SPEC.md로 저장합니다.

ai-issue의 PRODUCT_SPEC.md는 목적을 이렇게 시작합니다.

AI Issue Publisher is a CLI tool that publishes AI-generated work items as GitHub Issues.
The product exists to ensure valuable AI-generated work is preserved inside project backlogs.

요구사항은 번호가 붙은 문장으로 하나씩 씁니다. 나중에 인증 방식을 바꿀 때 추가된 요구사항은 이렇습니다.

## FR-011
The product shall support GitHub App login through device flow authentication.

사용자가 보는 동작만 쓰고, 어떤 라이브러리로 어떻게 구현하는지는 쓰지 않습니다. 그 내용은 다음 두 문서의 몫입니다.

3.3 기술 규칙과 구조를 정한다: TECH_STACK.md, ARCHITECTURE.md

TECH_STACK.md는 구현이 지켜야 할 규칙을 정합니다. 언어와 버전, 이름 짓기 규칙, 파일을 놓을 위치, 사용할 프레임워크가 여기에 들어갑니다. 구현하다가 사람도 AI도 이 규칙을 바꿔야겠다고 느끼면 코드보다 먼저 이 문서를 고칩니다. ai-issue에서는 토큰을 로컬에 저장하는 기능을 추가하면서 이런 한 줄이 들어갔습니다.

GitHub App device flow tokens must be stored locally with restricted file permissions.

ARCHITECTURE.md는 시스템의 모듈 구성과 데이터 흐름, 그리고 각 모듈의 책임 경계를 정의합니다. 같은 기능을 추가하면서 ai-issue에는 인증을 맡는 모듈이 새로 정의되었습니다.

# Authentication Resolution
Responsibilities:
* initiate device flow login
* obtain user access token
* persist token locally
* load token for publishing and diagnostics
Outputs:
GitHub App User Token
Authentication Resolution is not responsible for issue creation or repository selection.

마지막 문장을 주목하세요. 모듈이 무엇을 하는지만큼 무엇을 하지 않는지도 문서에 적혀 있습니다. 이 경계가 있으면 AI가 인증을 구현하다가 이슈 생성 코드까지 건드리는 일을 막을 수 있습니다.

두 문서도 PRODUCT_SPEC.md와 마찬가지로 대화형 AI와 함께 씁니다. 생성 프롬프트는 프롬프트 페이지에 있고, 결과는 .replworks/TECH_STACK.md와 .replworks/ARCHITECTURE.md로 저장합니다.

3.4 작업으로 나눈다: TASKS.md

마지막 문서는 TASKS.md입니다. 구조를 독립적으로 실행할 수 있는 작업 단위로 나누고, 다음에 할 일을 정합니다. 각 작업에는 완료 조건이 붙습니다. 위 요구사항이 TASKS.md에서는 이렇게 됩니다.

### Authentication
* [ ] Implement GitHub App device flow login
* [ ] Store and load GitHub App token locally
* [ ] Use stored token for publishing and diagnostics
Acceptance Criteria:
* `ai-issue login` obtains a GitHub App user access token
* Token is persisted locally
* Publishing works without manual PAT setup

완료 조건은 사용자가 관찰할 수 있는 결과로 씁니다. 코딩형 AI는 이 조건을 만족해야 작업을 끝냈다고 판단합니다.

이 네 조각은 한 요구에서 나온 것입니다. 요구사항 하나(FR-011)가 구조(Authentication Resolution)와 규칙(파일 권한)과 작업(Authentication)으로 나뉘어 각각의 문서에 기록됩니다. 아래는 이 네 조각이 한꺼번에 들어간 실제 커밋입니다.

이 커밋은 GitHub의 해당 커밋에서 볼 수 있습니다. 문서 구조가 현재의 .replworks/ 방식으로 바뀌기 전의 커밋이라서, 문서가 저장소 루트에 있고 TECH_STACK.md가 FRAMEWORK.md라는 이름이었습니다. 역할은 같습니다.

여기까지 하면 .replworks/ 아래에 문서 6종이 모두 있고, TASKS.md에는 첫 번째 작업과 그 완료 조건이 있어야 합니다.

4. 구현

구현은 코딩형 AI의 몫입니다. Codex와 Claude Code를 추천합니다. 코딩형 AI는 자율적으로 기능을 추가하지 않습니다. AGENTS.md가 그렇게 규정합니다.

Implement only the selected task.
Do not implement:
future work
roadmap items
optional features
assumptions
inferred requirements
Requirements must originate from:
PRODUCT_SPEC.md

4.1 개발 전에 문서를 검증한다

코딩을 시작하기 전에 코딩형 AI로 .replworks/의 네 문서를 검증합니다. 프롬프트 페이지의 검증 프롬프트가 문서가 서로 모순되지 않는지, 구현에 필요한 정보가 빠지지 않았는지 점검하고 수정합니다. 사람은 변경분을 검토해서 커밋한 뒤 개발을 시작합니다.

4.2 TASK 하나를 실행한다

사람이 TASKS.md에서 다음 TASK를 고르고 코딩형 AI에게 그 TASK를 수행하라고 지시합니다. AI는 AGENTS.md와 네 문서를 순서대로 읽은 뒤 그 TASK 하나만 구현합니다. 절차 중 두 가지가 특히 중요합니다.

첫째, 검증되지 않은 영역을 만나면 멈춥니다. TASK가 PRODUCT_SPEC.md나 ARCHITECTURE.md에 충분히 정의되지 않은 영역을 건드리면, AI는 해당 부분에 UNVERIFIED 표시를 하고 구현하지 않습니다. 사람이 확인하기 전에는 계속하지 않습니다. 추측으로 채워 넣어 구현하는 일을 막는 장치입니다.

둘째, 외부 시스템에 닿는 코드는 실제로 검증합니다. AGENTS.md는 외부 경계를 이렇게 정의합니다.

External boundary = any behavior not controlled by this codebase.
Examples:
third-party DOM
third-party API
browser runtime behavior

외부 경계를 건드리는 코드는 목(mock)만으로 테스트하면 완료가 아닙니다. 실제 대상을 상대로 한 E2E 테스트가 필요합니다. 목은 실제로 관찰했거나 문서에 적힌 동작만 흉내 낼 수 있습니다. ai-issue는 GitHub API를 사용하므로 이 규칙이 그대로 적용됩니다.

작업이 끝나면 AI는 멈춥니다. 다음 TASK를 스스로 시작하지 않습니다.

ai-issue의 인증 방식을 바꾼 TASK가 한 커밋에 남긴 변경입니다.

ARCHITECTURE.md | 19 ++++++++
FRAMEWORK.md | 2 +
PRODUCT_SPEC.md | 16 +++++++
TASKS.md | 14 ++++++
internal/adapter/github/client.go | 124 ++++++++++++++++++++++++++++++++++++++++++++++++---
internal/adapter/github/client_test.go | 14 ++++--
internal/adapter/github/device_flow_test.go | 60 +++++++++++++++++++++++++
internal/cli/diagnose.go | 33 ++++++++------
internal/cli/login.go | 93 ++++++++++++++++++++++++++++++++++++++
internal/cli/login_test.go | 56 +++++++++++++++++++++++
internal/cli/root.go | 1 +
internal/config/config.go | 56 +++++++++++++++++++++++
internal/config/token_test.go | 35 +++++++++++++++
13 files changed, 500 insertions(+), 23 deletions(-)

문서 네 개와 구현, 테스트가 한 커밋에 함께 있습니다. 문서의 규칙이 코드에 어떻게 반영되었는지도 확인할 수 있습니다. TECH_STACK.md에 추가된 “제한된 파일 권한으로 저장한다”는 규칙은 internal/config/config.go에서 이렇게 구현되었습니다.

if err := os.WriteFile(path, []byte(token+"\n"), 0o600); err != nil {

4.3 자동 검증을 통과한다

구현이 끝났다고 말할 수 있는 최소 조건이 있습니다.

  • 빌드가 성공한다.
  • 린트(코드 컨벤션 검사)를 통과한다.
  • 단위 테스트와 E2E 테스트를 통과한다.

ai-issue에서는 make build와 go test ./...로 확인하고, .golangci.yml과 .pre-commit-config.yaml, CI 워크플로우가 같은 검사를 반복합니다. 위 커밋의 메시지에도 이 검증의 흔적이 있습니다. 린트 도구가 지적한 fmt.Errorf 메시지를 고치는 항목이 마지막에 들어 있습니다.

4.4 사람이 검토하고 커밋한다

AI가 TASK 하나를 끝내면 사람은 코드와 문서 변경 전체를 git diff로 봅니다. 코드만 보지 않고 문서가 같이 바뀌었는지, TASK의 범위 밖을 건드리지 않았는지를 확인합니다. 문제가 없으면 커밋하고 다음 TASK로 갑니다. 이것이 REPL Works의 반복 단위인 1-Prompt = 1-Task = 1-Commit입니다. AI는 TASK 하나가 끝나면 멈추고, 사람은 그 결과를 커밋 하나로 남깁니다.

여기까지 하면 첫 TASK의 코드와 테스트와 문서 변경이 커밋 하나로 남아 있어야 합니다.

5. 검토·운영

5.1 TASK마다 검토한다

검토는 4.4에서 이미 했습니다. TASK가 하나 끝날 때마다 사람이 diff를 보고 커밋하는 이 주기가 REPL Works에서 품질을 지키는 가장 작은 단위입니다.

검토에서 놓치기 쉬운 것이 TASKS.md 자체입니다. ai-issue에서 실제로 있었던 일입니다. 위 커밋은 인증 기능을 구현했는데 TASKS.md의 해당 항목이 완료로 표시되지 않은 채 남았습니다. 나중에 문서를 정리하다가 발견했고, AI에게 체크해 달라고 지시해 고쳤습니다. 원인은 AGENTS.md에 있었습니다. 구현 절차가 TASKS.md를 완료로 갱신하라고 요구하지 않았고, AI는 규칙에 없는 일을 하지 않았습니다. 그래서 완료한 TASK를 TASKS.md에서 체크하는 단계를 AGENTS.md의 TASK 실행 절차에 추가했습니다.

이 일은 두 가지를 보여 줍니다. AI는 문서에 적힌 규칙을 지키지만 적혀 있지 않은 일은 하지 않습니다. 그리고 규칙의 빈틈은 사람이 발견해서 문서에 반영해야 합니다. 이 방식에서 문제를 고친다는 것은 AI에게 다시 말하는 것이 아니라 문서를 고치는 것입니다.

5.2 릴리즈 전에 최종 검토한다

릴리즈 전에는 개별 TASK가 아니라 제품 전체를 PRODUCT_SPEC.md와 대조합니다. 요구사항이 모두 충족되었는지, 제품의 방향과 사용자 경험이 의도와 일치하는지, 코드 품질과 보안과 성능에 문제가 없는지, 릴리즈할 준비가 되었는지와 커밋 이력이 정리되어 있는지를 봅니다. ai-issue는 GoReleaser로 릴리즈하고 Homebrew로 배포합니다.

5.3 운영하며 다음 반복을 시작한다

제품이 나간 뒤에는 사용자 피드백과 버그 리포트와 새로운 요구가 들어옵니다. 이것들도 같은 순서로 처리합니다. 새 요구가 제품의 동작을 바꾸면 PRODUCT_SPEC.md부터 고치고, 구조가 달라지면 ARCHITECTURE.md를, 할 일이 생기면 TASKS.md를 고친 다음 다음 TASK를 실행합니다. ai-issue에서도 기능 요청 이슈 #33이 PR #38로 이어져, 위에서 본 커밋이 되었습니다.

운영 → 피드백·버그 리포트 → PRODUCT_SPEC.md 갱신 → ARCHITECTURE.md 갱신 → TASKS.md 갱신 → 다음 TASK

여기까지 하면 릴리즈된 제품이 있고, 다음 반복에서 고칠 문서가 무엇인지 알고 있어야 합니다.

6. 결론

Models change. Projects survive.

AI 세션이 끝나거나 더 좋은 모델이 나와도 프로젝트의 기억은 문서와 Git에 남아 있습니다. 어떤 AI가 이어받아도 AGENTS.md부터 읽으면 같은 규칙으로 같은 프로젝트를 이어서 개발합니다. 이것이 대화가 길어질수록 흐려지는 AI 개발을 산으로 가지 않게 하는 방법입니다.

이 방식으로 만든 첫 상용 서비스는 와이파이 노트입니다.

시작하려면 새 저장소에 AGENTS.md를 복사하고 이 문서의 3장부터 순서대로 따라가면 됩니다. 문서 하나하나의 표준은 문서 페이지에, 단계마다 쓰는 프롬프트는 프롬프트 페이지에, 막히는 부분은 자주 묻는 질문에 있습니다.