From c5eaf5bbfba8682205a6b9cfdef5518b9fa54b5a Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Thu, 1 Oct 2026 14:53:36 +0900 Subject: [PATCH 1/2] docs: update README.md for clarity and consistency in project documentation standards --- README.md | 305 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 174 insertions(+), 131 deletions(-) diff --git a/README.md b/README.md index dc16558..fad595a 100644 --- a/README.md +++ b/README.md @@ -1,217 +1,260 @@ # ReplWorks Documents -AI-first project specifications for consistent software development. +AI가 소프트웨어를 구현할 때 **추측하지 않도록 만드는 프로젝트 문서 표준**입니다. -## Why? +ReplWorks Documents는 AI 코딩 에이전트가 프로젝트의 요구사항, 기술 스택, 아키텍처, 작업 범위를 임의로 해석하지 않도록 프로젝트의 핵심 정보를 명확한 문서로 정의합니다. -Modern AI coding agents are excellent at writing code but often struggle with project consistency. +핵심 원칙은 간단합니다. -Without clear constraints, AI agents tend to: +> **AI should not guess.** -- invent new folder structures -- create unnecessary files -- introduce inconsistent patterns -- assume incorrect framework versions -- drift away from established architecture +필요한 정보가 문서에 정의되어 있지 않다면 AI가 임의로 결정하는 것이 아니라, 구현을 멈추고 확인해야 합니다. -ReplWorks Documents provides reusable specifications that reduce guesswork and improve implementation consistency. +## 왜 필요한가? -The goal is simple: +AI 코딩 에이전트는 코드를 빠르게 작성할 수 있지만, 프로젝트에 이미 존재하는 규칙과 의도를 항상 정확하게 이해하는 것은 아닙니다. -> AI should not guess. +문서에 충분한 제약이 없다면 AI는 다음과 같은 결정을 스스로 만들어낼 수 있습니다. -## Philosophy +- 존재하지 않는 요구사항을 추론합니다. +- 새로운 디렉터리나 파일을 임의로 만듭니다. +- 기존 아키텍처와 다른 구조를 선택합니다. +- 사용하지 않기로 한 기술이나 라이브러리를 추가합니다. +- 동일한 기능을 다른 방식으로 다시 구현합니다. +- 정의되지 않은 외부 시스템의 동작을 추측합니다. +- 아직 구현하지 않기로 한 기능까지 미리 구현합니다. -Traditional documentation is written for humans. +ReplWorks Documents의 목적은 AI의 판단을 없애는 것이 아닙니다. -ReplWorks Documents is primarily written for AI agents. +**AI가 판단해도 되는 영역과 판단해서는 안 되는 영역을 문서로 구분하는 것**입니다. -Specifications focus on: +## 핵심 문서 -- constraints -- conventions -- structure -- deterministic behavior - -Instead of explaining how frameworks work, these documents define how projects should be implemented. - -## Repository Structure +하나의 프로젝트는 다음 다섯 가지 문서로 정의됩니다. ```text -. -├── AGENTS.md -├── AI_MEMORY.md -├── .repl/ -│ ├── agent.md -│ ├── architecture.md -│ └── tasks.md -│ -├── prompts/ -│ ├── AI_MEMORY_PROMPT.txt -│ ├── ARCHITECTURE_PROMPT.txt -│ ├── BLOG_PROMPT.txt -│ ├── DEVELOPMENT_LOG_PROMPT.txt -│ ├── FRAMEWORK_DISCOVERY.txt -│ ├── FRAMEWORK_PROMPT.txt -│ ├── IDEAS_PROMPT.txt -│ ├── JOURNAL_PROMPT.txt -│ ├── PITCHING_SCRIPT_PROMPT.txt -│ ├── PRODUCT_SPEC_PROMPT.txt -│ ├── REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt -│ └── TASKS_PROMPT.txt│ -└── frameworks/ - ├── react-vite.md - ├── nextjs.md - ├── laravel.md - └── ... +AGENTS.md +PRODUCT_SPEC.md +TECH_STACK.md +ARCHITECTURE.md +TASKS.md ``` -## Core Documents +각 문서는 서로 다른 책임을 가집니다. ### AGENTS.md -Defines repository-wide rules for AI agents. +AI 에이전트가 프로젝트 문서를 어떻게 읽고, 어떤 순서로 판단하고, 언제 구현을 중단해야 하는지를 정의합니다. + +또한 문서 간 우선순위와 구현 과정에서 지켜야 할 공통 규칙을 정의합니다. + +### PRODUCT_SPEC.md -### Framework Specifications +**제품이 무엇이며 무엇을 해야 하는지** 정의합니다. -Framework-specific conventions and constraints. +제품의 목적, 사용자, 기능, 동작, 입력과 출력, 제약사항 등 제품의 요구사항을 기록합니다. -Examples: +제품이 해야 할 일을 AI가 추측하지 않도록 하는 문서입니다. -- React + Vite -- Next.js -- Laravel -- FastAPI +### TECH_STACK.md -### Extension Specifications +**제품을 어떤 기술적 제약 안에서 구현해야 하는지** 정의합니다. -Package-specific rules that augment framework specifications. +사용할 기술, 버전, 필수 구성, 금지 사항 및 프로젝트의 개발 환경과 관련된 중요한 제약을 기록합니다. -Examples: +### ARCHITECTURE.md -- React Router -- i18next -- Zustand -- TanStack Query +**제품이 내부적으로 어떻게 동작하는지** 정의합니다. -### architecture.md +시스템의 책임 분리, 정보의 흐름, 구성 요소 간 관계, 주요 동작 구조와 반드시 유지해야 하는 불변조건을 설명합니다. -Project-specific architecture decisions. +가능한 한 특정 구현 기술에 종속되지 않는 구조적 정의를 담당합니다. -### tasks.md +### TASKS.md -Current project status and roadmap. +**현재 무엇을 구현해야 하는지** 정의합니다. -### AI_MEMORY.md +구현 작업을 작은 단위로 나누고, 현재 작업의 범위와 진행 상태를 관리합니다. -Long-term project memory preserved across future sessions. +TASKS.md에 정의되지 않은 미래 작업이나 아이디어를 AI가 임의로 구현해서는 안 됩니다. -## Example Workflow +## 문서의 관계 -Choose a framework: +다섯 문서는 서로 다른 질문에 답합니다. ```text -react-vite.md +PRODUCT_SPEC.md + │ + │ 무엇을 만드는가? + ▼ +TECH_STACK.md + │ + │ 어떤 기술적 제약으로 만드는가? + ▼ +ARCHITECTURE.md + │ + │ 어떻게 동작하는가? + ▼ +TASKS.md + │ + │ 지금 무엇을 구현하는가? + ▼ + Code ``` -Add required extensions: +`AGENTS.md`는 이 전체 과정에서 AI가 문서를 어떻게 사용해야 하는지를 정의합니다. + +문서 간 충돌이 발생할 경우 프로젝트에 정의된 **Source of Truth 순서**에 따라 판단합니다. + +## 구현 전 검증 + +ReplWorks에서는 문서를 작성했다고 바로 구현을 시작하지 않습니다. + +`PRODUCT_SPEC.md`, `TECH_STACK.md`, `ARCHITECTURE.md`를 하나의 구현 계약으로 보고 먼저 구현 가능 여부를 검증합니다. + +검증의 목적은 다음과 같습니다. + +- 요구사항이 빠져 있지 않은가? +- 아키텍처 책임이 정의되어 있는가? +- 필요한 기술적 제약이 정의되어 있는가? +- 동작이 모호하지 않은가? +- 입력과 출력이 정의되어 있는가? +- 구성 요소의 책임이 명확한가? +- 문서 사이에 충돌이 없는가? +- 구현을 위해 AI가 추측해야 하는 부분이 남아 있는가? + +구현을 막는 질문이 남아 있다면 구현을 시작하지 않습니다. + +> **모르는 것을 추측해서 구현하는 것보다, 구현을 멈추고 질문하는 것이 안전합니다.** + +## UNVERIFIED + +문서에 정의되지 않은 중요한 동작을 발견했을 때 AI는 임의로 가정을 만들어서는 안 됩니다. + +해당 영역을 `UNVERIFIED`로 표시하고 필요한 정보를 확인한 뒤 문서를 갱신해야 합니다. + +특히 외부 시스템이나 외부 런타임의 동작은 추측하지 않습니다. + +실제 동작을 확인할 수 있다면 관찰하고, 확인되지 않은 동작은 구현 계약에 포함시키지 않습니다. + +이 원칙을 통해 다음과 같은 문제를 줄일 수 있습니다. ```text -react-router.md -i18next.md -lucide-react.md +문서에 없음 + ↓ +AI가 추측 + ↓ +잘못된 구현 + ↓ +나중에 수정 ``` -Generate: +대신 다음 흐름을 사용합니다. ```text -framework.md +문서에 없음 + ↓ +UNVERIFIED + ↓ +확인 / 문서화 + ↓ +구현 ``` -Use with: +## Prompts + +이 저장소에는 핵심 문서를 작성하고 검증하기 위해 사용하는 프롬프트도 함께 제공합니다. ```text -agent.md -architecture.md -tasks.md +prompts/ +├── ARCHITECTURE_PROMPT.txt +├── PRODUCT_SPEC_PROMPT.txt +├── REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt +├── TASKS_PROMPT.txt +└── ... ``` -The AI agent now has deterministic implementation rules instead of making assumptions. - -## Design Principles +프롬프트는 문서를 대신하는 것이 아닙니다. -### Constraints Over Explanations +프롬프트는 **프로젝트 문서를 일관된 방식으로 만들고 검증하기 위한 도구**입니다. -Prefer: +일반적인 흐름은 다음과 같습니다. ```text -DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES +아이디어 / 요구사항 + ↓ +PRODUCT_SPEC.md + ↓ +TECH_STACK.md + ↓ +ARCHITECTURE.md + ↓ +Implementation Readiness Review + ↓ +TASKS.md + ↓ +AI Coding Agent + ↓ +Code ``` -Over: +문서를 만드는 과정은 사람과 AI의 대화를 통해 진행할 수 있습니다. -```text -Developers should generally avoid... -``` +AI가 질문하고, 사람이 결정하고, 결정된 내용을 문서에 반영합니다. -### Structure Over Flexibility +따라서 이 저장소의 문서는 단순한 템플릿 모음이 아니라 **AI와 함께 프로젝트를 정의하기 위한 문서 체계**입니다. -Consistency is more valuable than unlimited freedom. +## 저장소의 역할 -### Versions Matter +ReplWorks Documents는 ReplWorks에서 사용하는 프로젝트 문서 체계와 이를 만들기 위한 프롬프트의 원본을 관리합니다. -Framework specifications should define versions. +문서는 실제 프로젝트에 복사하여 사용하거나, 프로젝트의 요구사항에 맞게 수정하여 사용할 수 있습니다. -AI agents frequently assume incorrect versions when versions are not explicitly stated. +ReplWorks에서 이 문서 체계를 설명하고 기록하는 자료와 함께 사용할 수 있도록 설계되어 있습니다. -### Reuse Over Reinvention +## 핵심 원칙 -Framework specifications should be reusable across many projects. +### 1. AI는 추측하지 않습니다. -Project-specific decisions belong in architecture.md. +정의되지 않은 요구사항을 임의로 만들어서는 안 됩니다. -## Validation +### 2. 문서가 구현보다 먼저입니다. -Lint markdown files: +코드가 문서에 정의된 요구사항과 구조를 따라야 합니다. -```bash -npm run lint -``` +### 3. 각 문서는 하나의 책임을 가집니다. -Fix markdown issues: +제품 요구사항, 기술 스택, 아키텍처, 작업 계획을 하나의 문서에 섞지 않습니다. -```bash -npm run lint:fix -``` +### 4. 불확실성은 숨기지 않습니다. -Check formatting: +확인되지 않은 동작은 `UNVERIFIED`로 명시합니다. -```bash -npm run format:check -``` +### 5. 구현 범위를 임의로 확장하지 않습니다. -Format all documents: +현재 작업에 필요한 범위만 구현합니다. -```bash -npm run format -``` +### 6. 외부 동작을 추측하지 않습니다. -Validate repository: +외부 시스템의 실제 동작을 확인할 수 없는 경우 가정을 사실처럼 취급하지 않습니다. -```bash -npm run validate -``` +## 프로젝트의 목표 + +ReplWorks Documents가 해결하려는 문제는 **AI가 코드를 작성하지 못하는 문제**가 아닙니다. + +오히려 AI가 코드를 너무 쉽게 작성하기 때문에 발생하는 문제입니다. + +AI가 프로젝트의 의도를 정확하게 알지 못한 상태에서도 그럴듯한 코드를 만들어낼 수 있기 때문입니다. + +ReplWorks Documents는 프로젝트의 중요한 결정을 문서로 명시하고, AI가 그 경계를 벗어나지 않도록 합니다. -## Status +결국 목표는 다음과 같습니다. -Work in progress. +> **AI에게 더 많은 자유를 주는 것이 아니라, AI가 무엇을 알고 무엇을 모르는지를 명확하게 만드는 것.** -Current focus: +그리고 모르는 것이 있다면: -- framework specifications -- extension specifications -- specification composition -- AI implementation consistency +> **추측하지 않고 멈추는 것.** ## License From 6625177726122495cfd328864502cf29c549d03d Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Thu, 1 Oct 2026 15:01:07 +0900 Subject: [PATCH 2/2] refactor: add tech stack documentation for various frameworks and libraries --- README.md | 282 ++++++---------------- {frameworks => tech-stacks}/ASTRO.md | 0 {frameworks => tech-stacks}/FASTAPI.md | 0 {frameworks => tech-stacks}/GO_CLI.md | 0 {frameworks => tech-stacks}/NEXTJS.md | 0 {frameworks => tech-stacks}/NODE_CLI.md | 0 {frameworks => tech-stacks}/REACT_VITE.md | 0 {frameworks => tech-stacks}/VANILLA.md | 0 8 files changed, 73 insertions(+), 209 deletions(-) rename {frameworks => tech-stacks}/ASTRO.md (100%) rename {frameworks => tech-stacks}/FASTAPI.md (100%) rename {frameworks => tech-stacks}/GO_CLI.md (100%) rename {frameworks => tech-stacks}/NEXTJS.md (100%) rename {frameworks => tech-stacks}/NODE_CLI.md (100%) rename {frameworks => tech-stacks}/REACT_VITE.md (100%) rename {frameworks => tech-stacks}/VANILLA.md (100%) diff --git a/README.md b/README.md index fad595a..f6545b5 100644 --- a/README.md +++ b/README.md @@ -1,260 +1,124 @@ -# ReplWorks Documents +# REPLWorks Documents -AI가 소프트웨어를 구현할 때 **추측하지 않도록 만드는 프로젝트 문서 표준**입니다. - -ReplWorks Documents는 AI 코딩 에이전트가 프로젝트의 요구사항, 기술 스택, 아키텍처, 작업 범위를 임의로 해석하지 않도록 프로젝트의 핵심 정보를 명확한 문서로 정의합니다. - -핵심 원칙은 간단합니다. +**AI가 구현하기 전에, 프로젝트를 먼저 정의하는 문서 체계.** > **AI should not guess.** -필요한 정보가 문서에 정의되어 있지 않다면 AI가 임의로 결정하는 것이 아니라, 구현을 멈추고 확인해야 합니다. +AI coding agent의 문제는 코드를 못 쓴다는 것이 아닙니다. 정보가 부족해도 그럴듯한 코드를 너무 쉽게 만들어낸다는 것입니다. -## 왜 필요한가? +정의되지 않은 빈칸을 AI가 스스로 채우면, 코드는 동작해도 프로젝트는 의도한 방향에서 벗어납니다. -AI 코딩 에이전트는 코드를 빠르게 작성할 수 있지만, 프로젝트에 이미 존재하는 규칙과 의도를 항상 정확하게 이해하는 것은 아닙니다. +ReplWorks Documents는 이 문제를 문서로 해결합니다. -문서에 충분한 제약이 없다면 AI는 다음과 같은 결정을 스스로 만들어낼 수 있습니다. +- **무엇을 정의해야 하는지** 정해 두고 +- **정의되지 않은 것은 질문하거나 멈추도록** 규칙으로 만들고 +- 그 문서와 프롬프트를 **한 저장소에서 계속 개선**합니다. -- 존재하지 않는 요구사항을 추론합니다. -- 새로운 디렉터리나 파일을 임의로 만듭니다. -- 기존 아키텍처와 다른 구조를 선택합니다. -- 사용하지 않기로 한 기술이나 라이브러리를 추가합니다. -- 동일한 기능을 다른 방식으로 다시 구현합니다. -- 정의되지 않은 외부 시스템의 동작을 추측합니다. -- 아직 구현하지 않기로 한 기능까지 미리 구현합니다. +이 저장소는 ReplWorks의 AI-assisted development 문서 체계의 **원본(source repository)** 입니다. 문서 체계 자체를 개발하고 유지하는 곳이며, 애플리케이션 코드는 여기에 없습니다. -ReplWorks Documents의 목적은 AI의 판단을 없애는 것이 아닙니다. +## 어떻게 다른가 -**AI가 판단해도 되는 영역과 판단해서는 안 되는 영역을 문서로 구분하는 것**입니다. +> 아래는 설명을 위한 예시입니다. 실제 사례로 교체하세요. -## 핵심 문서 - -하나의 프로젝트는 다음 다섯 가지 문서로 정의됩니다. +### 문서가 없을 때 ```text -AGENTS.md -PRODUCT_SPEC.md -TECH_STACK.md -ARCHITECTURE.md -TASKS.md +요청: "회원 목록 페이지를 만들어줘" +AI: (ORM을 직접 고르고, src/features/ 디렉터리를 새로 만들고, 페이지네이션 방식을 임의로 결정) ``` -각 문서는 서로 다른 책임을 가집니다. - -### AGENTS.md - -AI 에이전트가 프로젝트 문서를 어떻게 읽고, 어떤 순서로 판단하고, 언제 구현을 중단해야 하는지를 정의합니다. - -또한 문서 간 우선순위와 구현 과정에서 지켜야 할 공통 규칙을 정의합니다. - -### PRODUCT_SPEC.md - -**제품이 무엇이며 무엇을 해야 하는지** 정의합니다. - -제품의 목적, 사용자, 기능, 동작, 입력과 출력, 제약사항 등 제품의 요구사항을 기록합니다. - -제품이 해야 할 일을 AI가 추측하지 않도록 하는 문서입니다. - -### TECH_STACK.md - -**제품을 어떤 기술적 제약 안에서 구현해야 하는지** 정의합니다. - -사용할 기술, 버전, 필수 구성, 금지 사항 및 프로젝트의 개발 환경과 관련된 중요한 제약을 기록합니다. - -### ARCHITECTURE.md - -**제품이 내부적으로 어떻게 동작하는지** 정의합니다. - -시스템의 책임 분리, 정보의 흐름, 구성 요소 간 관계, 주요 동작 구조와 반드시 유지해야 하는 불변조건을 설명합니다. - -가능한 한 특정 구현 기술에 종속되지 않는 구조적 정의를 담당합니다. - -### TASKS.md - -**현재 무엇을 구현해야 하는지** 정의합니다. - -구현 작업을 작은 단위로 나누고, 현재 작업의 범위와 진행 상태를 관리합니다. - -TASKS.md에 정의되지 않은 미래 작업이나 아이디어를 AI가 임의로 구현해서는 안 됩니다. - -## 문서의 관계 - -다섯 문서는 서로 다른 질문에 답합니다. +### 문서가 있을 때 ```text -PRODUCT_SPEC.md - │ - │ 무엇을 만드는가? - ▼ -TECH_STACK.md - │ - │ 어떤 기술적 제약으로 만드는가? - ▼ -ARCHITECTURE.md - │ - │ 어떻게 동작하는가? - ▼ -TASKS.md - │ - │ 지금 무엇을 구현하는가? - ▼ - Code +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES +DO_NOT_ADD_DEPENDENCIES_NOT_LISTED_IN_TECH_STACK +IF_REQUIREMENT_IS_UNDEFINED_ASK_BEFORE_IMPLEMENTING ``` -`AGENTS.md`는 이 전체 과정에서 AI가 문서를 어떻게 사용해야 하는지를 정의합니다. - -문서 간 충돌이 발생할 경우 프로젝트에 정의된 **Source of Truth 순서**에 따라 판단합니다. - -## 구현 전 검증 - -ReplWorks에서는 문서를 작성했다고 바로 구현을 시작하지 않습니다. - -`PRODUCT_SPEC.md`, `TECH_STACK.md`, `ARCHITECTURE.md`를 하나의 구현 계약으로 보고 먼저 구현 가능 여부를 검증합니다. - -검증의 목적은 다음과 같습니다. - -- 요구사항이 빠져 있지 않은가? -- 아키텍처 책임이 정의되어 있는가? -- 필요한 기술적 제약이 정의되어 있는가? -- 동작이 모호하지 않은가? -- 입력과 출력이 정의되어 있는가? -- 구성 요소의 책임이 명확한가? -- 문서 사이에 충돌이 없는가? -- 구현을 위해 AI가 추측해야 하는 부분이 남아 있는가? - -구현을 막는 질문이 남아 있다면 구현을 시작하지 않습니다. - -> **모르는 것을 추측해서 구현하는 것보다, 구현을 멈추고 질문하는 것이 안전합니다.** - -## UNVERIFIED +설명보다 **구현자가 따라야 할 제약**을 우선합니다. 제약은 구현 결과에 직접 영향을 주는 형태로 씁니다. -문서에 정의되지 않은 중요한 동작을 발견했을 때 AI는 임의로 가정을 만들어서는 안 됩니다. - -해당 영역을 `UNVERIFIED`로 표시하고 필요한 정보를 확인한 뒤 문서를 갱신해야 합니다. - -특히 외부 시스템이나 외부 런타임의 동작은 추측하지 않습니다. - -실제 동작을 확인할 수 있다면 관찰하고, 확인되지 않은 동작은 구현 계약에 포함시키지 않습니다. - -이 원칙을 통해 다음과 같은 문제를 줄일 수 있습니다. +## 저장소 구성 ```text -문서에 없음 - ↓ -AI가 추측 - ↓ -잘못된 구현 - ↓ -나중에 수정 +. +├── AGENTS.md # 이 저장소를 관리하는 AI agent의 규칙 +├── CHANGELOG.md # 규칙 변경 기록 +├── tech-stacks/ # 재사용 가능한 tech stack specification +├── prompts/ # 문서를 만들고 검증하는 프롬프트 +├── docs/ # 보조 자료와 기록 (source of truth 아님) +└── package.json # 문서 검증 도구 (Markdownlint, Prettier, Husky) ``` -대신 다음 흐름을 사용합니다. +| 경로 | 역할 | +| -------------- | ----------------------------------------------------------------------- | +| `AGENTS.md` | 저장소의 목적, 문서 작성 원칙, specification 관리 방법 | +| `tech-stacks/` | 특정 프로젝트에 종속되지 않고 여러 프로젝트에서 반복 사용하는 기술 규칙 | +| `prompts/` | specification 자체가 아니라, specification을 만들고 검증하는 도구 | +| `docs/` | 작성 과정에서 생긴 보조 기록 | -```text -문서에 없음 - ↓ -UNVERIFIED - ↓ -확인 / 문서화 - ↓ -구현 -``` +## 사용 방법 -## Prompts +1. `prompts/`의 프롬프트로 AI와 함께 프로젝트 문서(요구사항, 기술 스택, 아키텍처, 작업 계획)를 정의합니다. +2. 프로젝트가 쓰는 기술에 맞는 `tech-stacks/`의 specification을 프로젝트에 가져옵니다. +3. 구현 에이전트에게 문서를 전달합니다. 문서에 없는 내용은 에이전트가 질문하거나 멈춥니다. +4. 진행 중 발견한 AI의 실수와 문서의 빈틈을 이 저장소로 되돌려 반영합니다. -이 저장소에는 핵심 문서를 작성하고 검증하기 위해 사용하는 프롬프트도 함께 제공합니다. +## 문서의 원칙 -```text -prompts/ -├── ARCHITECTURE_PROMPT.txt -├── PRODUCT_SPEC_PROMPT.txt -├── REVIEW_IMPLEMENTATION_READINESS_PROMPT.txt -├── TASKS_PROMPT.txt -└── ... -``` +**AI는 추측하지 않습니다.** 정의되지 않은 요구사항은 AI가 임의로 결정하지 않습니다. 정보가 없으면 질문하거나 구현을 중단합니다. -프롬프트는 문서를 대신하는 것이 아닙니다. +**제약은 명확해야 합니다.** 구현 결과에 직접 영향을 주는 규칙을 설명보다 우선합니다. -프롬프트는 **프로젝트 문서를 일관된 방식으로 만들고 검증하기 위한 도구**입니다. +**문서는 하나의 책임만 가집니다.** 제품이 무엇인지, 어떤 기술을 쓰는지, 어떻게 동작하는지, 무엇을 구현할지를 한 문서에 섞지 않습니다. -일반적인 흐름은 다음과 같습니다. +**규칙은 실제 문제에서 나옵니다.** 일어날 수 있는 모든 문제를 미리 규칙으로 만들지 않습니다. 실제 프로젝트에서 반복된 AI의 실수를 관찰하고, 그 문제를 막는 규칙만 추가합니다. + +## 운영 방법 ```text -아이디어 / 요구사항 - ↓ -PRODUCT_SPEC.md +실제 프로젝트에서 사용 ↓ -TECH_STACK.md +문제 또는 개선점 발견 ↓ -ARCHITECTURE.md +문서 / 프롬프트 개선 ↓ -Implementation Readiness Review +Markdown 검증 → Commit ↓ -TASKS.md +다른 프로젝트에서 재사용 ↓ -AI Coding Agent - ↓ -Code +(반복) ``` -문서를 만드는 과정은 사람과 AI의 대화를 통해 진행할 수 있습니다. - -AI가 질문하고, 사람이 결정하고, 결정된 내용을 문서에 반영합니다. - -따라서 이 저장소의 문서는 단순한 템플릿 모음이 아니라 **AI와 함께 프로젝트를 정의하기 위한 문서 체계**입니다. - -## 저장소의 역할 - -ReplWorks Documents는 ReplWorks에서 사용하는 프로젝트 문서 체계와 이를 만들기 위한 프롬프트의 원본을 관리합니다. - -문서는 실제 프로젝트에 복사하여 사용하거나, 프로젝트의 요구사항에 맞게 수정하여 사용할 수 있습니다. +이 저장소의 문서는 처음부터 완성된 규칙집이 아니라, 실제 개발 경험으로 계속 진화하는 문서 체계입니다. -ReplWorks에서 이 문서 체계를 설명하고 기록하는 자료와 함께 사용할 수 있도록 설계되어 있습니다. +## 문서를 변경할 때 -## 핵심 원칙 +- **새 요구사항을 발견했다면** 먼저 여러 프로젝트에서 재사용될 규칙인지 판단합니다. 특정 프로젝트에만 필요하다면 그 프로젝트의 문서에 남깁니다. +- **AI의 반복적인 실수를 발견했다면** 이를 막는 specification 또는 prompt를 추가하거나 수정합니다. 근거는 실제로 발생한 문제여야 합니다. +- **기존 규칙을 변경한다면** 해당 specification을 쓰는 프로젝트에 영향이 있는지 확인하고, `CHANGELOG.md`에 기록합니다. -### 1. AI는 추측하지 않습니다. +### Pull Request 체크리스트 -정의되지 않은 요구사항을 임의로 만들어서는 안 됩니다. +1. 이 변경이 왜 필요한지 설명했습니다. +2. 기존 문서와 책임이 중복되지 않습니다. +3. 특정 프로젝트의 요구사항을 공통 규칙으로 잘못 추가하지 않았습니다. +4. AI의 실제 구현 문제를 해결하는 변경입니다. +5. 기존 프로젝트에 영향을 줄 수 있는 변경이라면 `CHANGELOG.md`에 기록했습니다. +6. `npm run validate`를 통과합니다. -### 2. 문서가 구현보다 먼저입니다. +## 로컬 개발 환경 -코드가 문서에 정의된 요구사항과 구조를 따라야 합니다. +Node.js 기반 도구로 문서 품질을 검증합니다. Husky가 commit 시점에 변경된 파일의 formatting을 자동으로 관리합니다. -### 3. 각 문서는 하나의 책임을 가집니다. +```bash +npm install # 의존성 설치 +npm run validate # lint + format 전체 검증 -제품 요구사항, 기술 스택, 아키텍처, 작업 계획을 하나의 문서에 섞지 않습니다. - -### 4. 불확실성은 숨기지 않습니다. - -확인되지 않은 동작은 `UNVERIFIED`로 명시합니다. - -### 5. 구현 범위를 임의로 확장하지 않습니다. - -현재 작업에 필요한 범위만 구현합니다. - -### 6. 외부 동작을 추측하지 않습니다. - -외부 시스템의 실제 동작을 확인할 수 없는 경우 가정을 사실처럼 취급하지 않습니다. - -## 프로젝트의 목표 - -ReplWorks Documents가 해결하려는 문제는 **AI가 코드를 작성하지 못하는 문제**가 아닙니다. - -오히려 AI가 코드를 너무 쉽게 작성하기 때문에 발생하는 문제입니다. - -AI가 프로젝트의 의도를 정확하게 알지 못한 상태에서도 그럴듯한 코드를 만들어낼 수 있기 때문입니다. - -ReplWorks Documents는 프로젝트의 중요한 결정을 문서로 명시하고, AI가 그 경계를 벗어나지 않도록 합니다. - -결국 목표는 다음과 같습니다. - -> **AI에게 더 많은 자유를 주는 것이 아니라, AI가 무엇을 알고 무엇을 모르는지를 명확하게 만드는 것.** - -그리고 모르는 것이 있다면: - -> **추측하지 않고 멈추는 것.** +npm run lint # Markdown lint +npm run lint:fix # lint 자동 수정 +npm run format:check # formatting 확인 +npm run format # formatting 적용 +``` ## License diff --git a/frameworks/ASTRO.md b/tech-stacks/ASTRO.md similarity index 100% rename from frameworks/ASTRO.md rename to tech-stacks/ASTRO.md diff --git a/frameworks/FASTAPI.md b/tech-stacks/FASTAPI.md similarity index 100% rename from frameworks/FASTAPI.md rename to tech-stacks/FASTAPI.md diff --git a/frameworks/GO_CLI.md b/tech-stacks/GO_CLI.md similarity index 100% rename from frameworks/GO_CLI.md rename to tech-stacks/GO_CLI.md diff --git a/frameworks/NEXTJS.md b/tech-stacks/NEXTJS.md similarity index 100% rename from frameworks/NEXTJS.md rename to tech-stacks/NEXTJS.md diff --git a/frameworks/NODE_CLI.md b/tech-stacks/NODE_CLI.md similarity index 100% rename from frameworks/NODE_CLI.md rename to tech-stacks/NODE_CLI.md diff --git a/frameworks/REACT_VITE.md b/tech-stacks/REACT_VITE.md similarity index 100% rename from frameworks/REACT_VITE.md rename to tech-stacks/REACT_VITE.md diff --git a/frameworks/VANILLA.md b/tech-stacks/VANILLA.md similarity index 100% rename from frameworks/VANILLA.md rename to tech-stacks/VANILLA.md