From 2b95d1ccae5316c25c4e93f5d9d3eb994dede0b6 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Fri, 12 Jun 2026 22:45:17 +0900 Subject: [PATCH 1/3] docs: review `/documents` content --- src/content.config.ts | 7 + src/content/documents/agents.mdx | 197 +++++- src/content/documents/architecture.mdx | 187 ++++- src/content/documents/example-agents.mdx | 237 +++++++ .../documents/example-architecture.mdx | 642 ++++++++++++++++++ src/content/documents/example-ideas-md.mdx | 513 ++++++++++++++ .../documents/example-pitching-script.mdx | 370 ++++++++++ .../documents/example-product-spec.mdx | 10 + src/content/documents/example-tasks.mdx | 259 +++++++ src/content/documents/framework.mdx | 195 ++++++ src/content/documents/ideas.mdx | 148 +++- src/content/documents/index.mdx | 311 ++++++++- src/content/documents/pitching-script.mdx | 136 +++- src/content/documents/product-spec.mdx | 164 ++++- src/content/documents/tasks.mdx | 204 +++++- src/content/frameworks/astro.mdx | 311 +++++++++ src/content/frameworks/fastapi.mdx | 268 ++++++++ src/content/frameworks/golang-cli.mdx | 415 +++++++++++ src/content/frameworks/nextjs.mdx | 338 +++++++++ src/content/frameworks/react-vite.mdx | 343 ++++++++++ src/content/frameworks/vanilla.mdx | 270 ++++++++ src/lib/site.ts | 2 + 22 files changed, 5432 insertions(+), 95 deletions(-) create mode 100644 src/content/documents/example-agents.mdx create mode 100644 src/content/documents/example-architecture.mdx create mode 100644 src/content/documents/example-ideas-md.mdx create mode 100644 src/content/documents/example-pitching-script.mdx create mode 100644 src/content/documents/example-product-spec.mdx create mode 100644 src/content/documents/example-tasks.mdx create mode 100644 src/content/documents/framework.mdx create mode 100644 src/content/frameworks/astro.mdx create mode 100644 src/content/frameworks/fastapi.mdx create mode 100644 src/content/frameworks/golang-cli.mdx create mode 100644 src/content/frameworks/nextjs.mdx create mode 100644 src/content/frameworks/react-vite.mdx create mode 100644 src/content/frameworks/vanilla.mdx diff --git a/src/content.config.ts b/src/content.config.ts index a5ce50e..1d5356c 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -31,6 +31,13 @@ export const collections = { }), schema: baseCollectionSchema, }), + frameworks: defineCollection({ + loader: glob({ + base: './src/content/frameworks', + pattern: '**/*.{md,mdx}', + }), + schema: baseCollectionSchema, + }), tools: defineCollection({ loader: glob({ base: './src/content/tools', diff --git a/src/content/documents/agents.mdx b/src/content/documents/agents.mdx index fe83f83..955e112 100644 --- a/src/content/documents/agents.mdx +++ b/src/content/documents/agents.mdx @@ -1,31 +1,196 @@ --- title: 'AGENTS.md' version: 'v1' -description: 'Project entrypoint and operating rules for AI collaborators.' +description: 'AGENTS.md는 AI를 위한 프로젝트 진입점이다.' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +모든 AI는 프로젝트 작업을 시작하기 전에 AGENTS.md를 먼저 읽는다. -Define the authoritative reading order, scope boundaries, and implementation rules. +--- + +# Purpose + +다음 질문에 답한다. + +```text +어떤 문서를 읽어야 하는가? + +어떤 순서로 읽어야 하는가? + +무엇을 구현할 수 있는가? + +무엇을 구현하면 안 되는가? +``` + +--- + +AGENTS.md는 프로젝트 운영 규칙을 정의한다. + +--- + +# Inputs + +일반적으로 다음 정보를 기반으로 작성한다. + +- PRODUCT_SPEC.md +- ARCHITECTURE.md +- FRAMEWORK.md +- TASKS.md +- 프로젝트 운영 정책 + +--- + +# Outputs + +다음 내용을 정의한다. + +- 문서 읽기 순서 +- 권한 범위 +- 구현 규칙 +- 작업 절차 +- 중단 조건 +- 변경 규칙 + +--- + +# Lifecycle + +프로젝트 초기 단계에 생성한다. + +--- + +운영 규칙이 변경될 때만 수정한다. + +--- + +일반적인 기능 개발로는 수정하지 않는다. + +--- + +# Relationship + +```text +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +TASKS.md +↓ +AGENTS.md +↓ +AI Execution +``` + +--- + +AGENTS.md는 다른 문서를 대체하지 않는다. + +--- + +AGENTS.md는 어떤 문서를 어떻게 사용해야 하는지 설명한다. + +--- + +# AI Usage + +모든 AI가 반드시 읽어야 하는 문서다. + +--- + +프로젝트 작업의 시작점은 AGENTS.md다. + +--- + +새로운 세션에서도 AGENTS.md부터 읽는다. + +--- + +새로운 모델에서도 AGENTS.md부터 읽는다. + +--- + +# Common Responsibilities + +일반적으로 다음 내용을 포함한다. + +```text +Document Order + +Source of Truth + +Scope Control + +Implementation Rules + +Task Execution Rules + +Architecture Update Rules + +Success Criteria +``` + +--- + +# Generate With + +AGENTS.md는 ReplWorks 에서 표준 AGENTS.md를 제공한다. + +--- + +프로젝트 운영 방식이 바뀔 때만 수정한다. + +--- + +조직 또는 개인은 재사용 가능한 AGENTS.md 템플릿을 구축할 수 있다. + +--- + +# Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 AGENTS.md 작성 방식을 확인할 수 있다. + +→ [Example AGENTS.md](./example-agents) + +--- + +예시는 다음 내용을 포함한다. + +- 문서 우선순위 +- 작업 범위 제어 +- 구현 규칙 +- 완료 기준 + +--- + +# Key Principle + +좋은 AGENTS.md는 기능을 설명하지 않는다. + +좋은 AGENTS.md는 AI가 어떻게 작업해야 하는지 설명한다. + +--- -## Inputs +# Why It Matters -- repository context -- product specification -- architecture -- tasks +AI는 프로젝트의 전체 맥락을 알지 못한다. -## Outputs +--- + +AGENTS.md는 AI를 올바른 문서로 안내한다. + +--- + +PRODUCT_SPEC.md가 무엇을 만들지 정의한다면, -- collaboration rules -- task execution order -- scope limits +ARCHITECTURE.md는 어떻게 구성할지 정의한다. -## Lifecycle +FRAMEWORK.md는 어떻게 구현할지 정의한다. -Reviewed first, then updated only when operating rules or authoritative sources change. +TASKS.md는 무엇을 해야 하는지 정의한다. -## Relationships +--- -Depends on `PRODUCT_SPEC.md`, `ARCHITECTURE.md`, and `TASKS.md`. +AGENTS.md는 무엇을 먼저 읽어야 하는지 정의한다. diff --git a/src/content/documents/architecture.mdx b/src/content/documents/architecture.mdx index 10d4727..c036a31 100644 --- a/src/content/documents/architecture.mdx +++ b/src/content/documents/architecture.mdx @@ -1,30 +1,187 @@ --- title: 'ARCHITECTURE.md' version: 'v1' -description: 'Technical structure and repository constraints for REPL Works.' +description: 'ARCHITECTURE.md는 프로젝트의 기술 구조를 정의하는 문서다.' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +이 문서의 목적은 제품 요구사항을 정의하는 것이 아니다. -Describe the system design, technical structure, and repository constraints. +제품을 어떤 구조로 구현할 것인지 정의하는 것이다. -## Inputs +--- + +# Purpose + +다음 질문에 답한다. + +```text +프로젝트는 어떻게 구성되는가? + +콘텐츠는 어디에 위치하는가? + +시스템은 어떻게 연결되는가? -- `PRODUCT_SPEC.md` -- repository structure -- implementation constraints +어떤 제약을 따라야 하는가? +``` -## Outputs +--- + +ARCHITECTURE.md는 프로젝트의 기술적 진실(Source of Truth)이다. + +--- + +# Inputs -- content model -- routing plan -- file placement rules +일반적으로 다음 정보를 기반으로 작성한다. -## Lifecycle +* PRODUCT_SPEC.md +* 선택된 기술 스택 +* 프로젝트 요구사항 +* 운영 제약 +* 배포 환경 -Updated when technical structure or implementation constraints change. +--- -## Relationships +# Outputs + +다음 내용을 정의한다. + +* 시스템 구조 +* 저장소 구조 +* 콘텐츠 구조 +* 라우팅 구조 +* 데이터 흐름 +* 모듈 구조 +* 구현 경계 +* 운영 제약 + +--- + +# Lifecycle + +PRODUCT_SPEC.md 이후 작성한다. + +--- + +제품 구조가 변경될 경우 업데이트한다. + +--- + +기술 구조가 변경될 경우 업데이트한다. + +--- + +단순 구현 작업으로는 수정하지 않는다. + +--- + +# Relationship + +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +TASKS.md +``` + +--- + +PRODUCT_SPEC.md는 무엇을 만들지 정의한다. + +--- + +ARCHITECTURE.md는 어떻게 구성할지 정의한다. + +--- + +FRAMEWORK.md는 어떻게 구현할지 정의한다. + +--- + +TASKS.md는 무엇을 해야 하는지 정의한다. + +--- + +# AI Usage + +Planning AI가 반드시 읽어야 하는 문서다. + +--- + +Execution AI도 반드시 읽어야 하는 문서다. + +--- + +기술 구조에 대한 최종 기준은 ARCHITECTURE.md다. + +--- + +# Generate With + +ARCHITECTURE.md는 일반적으로 다음 프롬프트를 통해 생성한다. + +→ [Architecture Design Prompt](/prompts/architecture-design) + +--- + +Architecture Design Prompt는 다음을 수행한다. + +* 저장소 구조 설계 +* 콘텐츠 구조 설계 +* 라우팅 설계 +* 구현 경계 정의 +* 운영 제약 정의 + +--- + +# Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 ARCHITECTURE.md 작성 방식을 확인할 수 있다. + +→ [Example ARCHITECTURE.md](./example-architecture) + +--- + +예시는 다음 내용을 포함한다. + +* 시스템 구조 +* 콘텐츠 구조 +* 라우팅 구조 +* 모듈 구조 +* 제약 사항 + +--- + +# Key Principle + +좋은 ARCHITECTURE.md는 기능을 설명하지 않는다. + +좋은 ARCHITECTURE.md는 구조를 설명한다. + +--- + +# Why It Matters + +AI는 구조가 없으면 기능 중심으로 구현하려는 경향이 있다. + +--- + +ARCHITECTURE.md는 프로젝트 전체 구조를 명확하게 정의한다. + +--- + +PRODUCT_SPEC.md가 목적지라면, + +ARCHITECTURE.md는 설계도다. + +--- -Constrained by `PRODUCT_SPEC.md` and implemented through `TASKS.md`. +모든 구현은 ARCHITECTURE.md와 일치해야 한다. diff --git a/src/content/documents/example-agents.mdx b/src/content/documents/example-agents.mdx new file mode 100644 index 0000000..759449b --- /dev/null +++ b/src/content/documents/example-agents.mdx @@ -0,0 +1,237 @@ +--- +title: 'AGENTS.md 예시' +version: 'v1' +description: 'ReplWorks가 제공하는 AGENTS.md 입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# AGENTS.md + +## DOCUMENT_ORDER + +1. AGENTS.md +2. PRODUCT_SPEC.md +3. ARCHITECTURE.md +4. FRAMEWORK.md +5. TASKS.md + +Only these documents are authoritative. + +--- + +## IGNORE + +Ignore all files under: + +```text +docs/ +``` + +Never use files in docs/ as requirements. + +Never implement features described only in docs/. + +--- + +## SOURCE_OF_TRUTH + +Product Requirements: + +```text +PRODUCT_SPEC.md +``` + +Architecture: + +```text +ARCHITECTURE.md +``` + +Implementation Constraints: + +```text +FRAMEWORK.md +``` + +Execution Plan: + +```text +TASKS.md +``` + +If a conflict exists: + +```text +PRODUCT_SPEC.md +> +ARCHITECTURE.md +> +FRAMEWORK.md +> +TASKS.md +> +everything else +``` + +--- + +## DOCUMENT_RESPONSIBILITIES + +PRODUCT_SPEC.md defines: + +```text +What the product is. +What the product does. +``` + +ARCHITECTURE.md defines: + +```text +How the product works. +``` + +FRAMEWORK.md defines: + +```text +How the product must be implemented. +``` + +TASKS.md defines: + +```text +What should be implemented next. +``` + +Do not move responsibilities between documents. + +--- + +## IMPLEMENTATION_RULES + +Implement only the selected task. + +Do not implement: + +* future work +* roadmap items +* optional features +* assumptions +* inferred requirements + +Requirements must originate from: + +```text +PRODUCT_SPEC.md +``` + +Implementation must follow: + +```text +ARCHITECTURE.md +FRAMEWORK.md +``` + +--- + +## TASK_EXECUTION + +For every task: + +1. Read PRODUCT_SPEC.md +2. Read ARCHITECTURE.md +3. Read FRAMEWORK.md +4. Read task definition +5. Implement +6. Test +7. Stop + +Do not start another task automatically. + +--- + +## PRODUCT_CHANGES + +If implementation reveals missing product requirements: + +Stop. + +Do not invent requirements. + +Update: + +```text +PRODUCT_SPEC.md +``` + +before implementation continues. + +--- + +## ARCHITECTURE_CHANGES + +If implementation requires architecture changes: + +1. Update ARCHITECTURE.md +2. Update implementation + +Never allow architecture and code to diverge. + +--- + +## FRAMEWORK_CHANGES + +If implementation requires framework changes: + +1. Update FRAMEWORK.md +2. Update implementation + +Never allow framework and code to diverge. + +--- + +## TASK_CHANGES + +If implementation invalidates a task: + +Update TASKS.md. + +--- + +## DESIGN_RULES + +Prefer: + +* simple +* explicit +* minimal + +Avoid: + +* abstraction without use +* premature optimization +* speculative features + +--- + +## FILE_CREATION + +Do not create new top-level documents unless explicitly requested. + +Prefer modifying existing files. + +--- + +## SUCCESS_CRITERIA + +Task is complete only when: + +* product requirements satisfied +* architectural requirements satisfied +* framework constraints satisfied +* acceptance criteria satisfied +* code runs +* tests pass + +Then stop. +`````` diff --git a/src/content/documents/example-architecture.mdx b/src/content/documents/example-architecture.mdx new file mode 100644 index 0000000..6e2fe36 --- /dev/null +++ b/src/content/documents/example-architecture.mdx @@ -0,0 +1,642 @@ +--- +title: 'ARCHITECTURE.md 예시' +version: 'v1' +description: '아키텍쳐 prompt로 만든 AGENTS.md 입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# ARCHITECTURE.md + +Version 3.0 + +## PROJECT + +REPL Works Website + +--- + +## PURPOSE + +Documentation Platform for REPL Works. + +Goal: + +```text +Establish REPL Works as an AI-Native Product Development Framework. +``` + +--- + +## PRODUCT TYPE + +```text +Documentation Platform +``` + +Not: + +```text +SaaS + +Dashboard + +Community Platform + +Social Network + +Developer Portal + +AI Tool +``` + +--- + +## PRIMARY NAVIGATION + +```text +Home + +Workflow + +Prompts + +Documents + +Tools + +Showcase + +FAQ +``` + +--- + +## PRIMARY USER JOURNEY + +```text +Home +↓ +Workflow +↓ +Prompts +↓ +Documents +↓ +Tools +↓ +Showcase +↓ +GitHub +``` + +--- + +## CONTENT MODEL + +Content First + +Design Second + +--- + +Content Source + +```text +MDX +``` + +--- + +Collections + +```text +workflow + +prompts + +documents + +tools + +showcase + +faq +``` + +--- + +## PAGE RESPONSIBILITIES + +### Home + +Purpose + +```text +Introduce REPL Works + +Explain Core Philosophy + +Provide Entry Points +``` + +--- + +### Workflow + +Purpose + +```text +Explain REPL Works Methodology +``` + +--- + +Must describe: + +```text +Idea Refinement + +Product Definition + +Architecture Design + +Task Planning + +AI Execution + +Review + +Release + +Continuous Improvement +``` + +--- + +### Prompts + +Purpose + +```text +Provide Reusable Prompts +``` + +--- + +Content Examples + +```text +IDEAS Prompt + +PITCHING Prompt + +PRODUCT_SPEC Prompt + +ARCHITECTURE Prompt + +TASKS Prompt + +Review Prompt +``` + +--- + +### Documents + +Purpose + +```text +Provide Reusable Document Standards +``` + +--- + +Content Examples + +```text +AGENTS.md + +PRODUCT_SPEC.md + +ARCHITECTURE.md + +TASKS.md +``` + +--- + +### Tools + +Purpose + +```text +Provide REPL Works Tooling +``` + +--- + +Initial Tools + +```text +ai-issue +``` + +--- + +Future Tools + +```text +ai-prompt +``` + +--- + +### Showcase + +Purpose + +```text +Demonstrate Real Adoption +``` + +--- + +Definition + +```text +REPL Works Compatible Projects +``` + +--- + +Initial Entries + +```text +REPL Works Website + +ai-issue + +Wifi Note +``` + +--- + +Each Showcase Entry Must Include + +```text +Project + +Purpose + +Workflow Usage + +Documents Used + +Tools Used +``` + +--- + +### FAQ + +Purpose + +```text +Answer Common Questions +``` + +--- + +## CONTENT ORGANIZATION + +```text +src/content/ + +workflow/ + +prompts/ + +documents/ + +tools/ + +showcase/ + +faq/ +``` + +--- + +All content must be stored as: + +```text +MDX +``` + +--- + +Large content blocks must not be embedded directly inside page components. + +--- + +Content must remain independent from presentation. + +--- + +## ROUTING STRUCTURE + +```text +/ + +/workflow + +/prompts + +/documents + +/tools + +/showcase + +/faq +``` + +--- + +Content detail pages + +```text +/workflow/[slug] + +/prompts/[slug] + +/documents/[slug] + +/tools/[slug] + +/showcase/[slug] + +/faq/[slug] +``` + +--- + +## GITHUB + +GitHub is the primary external asset. + +--- + +Website Responsibilities + +```text +Explain + +Teach + +Distribute +``` + +--- + +GitHub Responsibilities + +```text +Source Code + +Issues + +Pull Requests + +Releases +``` + +--- + +Website must never replace GitHub. + +--- + +## SEARCH + +Required + +--- + +Search Scope + +```text +Workflow + +Prompts + +Documents + +Tools + +Showcase + +FAQ +``` + +--- + +Implementation + +```text +Pagefind +``` + +--- + +## SHOWCASE POLICY + +Showcase is reserved for: + +```text +REPL Works Compatible Projects +``` + +--- + +Do Not Include + +```text +Prompt Repositories + +Document Repositories + +Template Repositories +``` + +--- + +Those belong under: + +```text +Prompts + +Documents +``` + +--- + +## STACK + +Required + +```text +Node.js >= 24 + +npm >= 11 + +Astro >= 6 + +TypeScript >= 5 + +Tailwind CSS >= 4 +``` + +--- + +Package Manager + +```text +npm +``` + +--- + +Framework + +```text +Astro +``` + +--- + +Content + +```text +MDX +``` + +--- + +Search + +```text +Pagefind +``` + +--- + +Hosting + +```text +GitHub Pages +``` + +--- + +CI/CD + +```text +GitHub Actions +``` + +--- + +## CONSTRAINTS + +All pages must support: + +```text +Static Export +``` + +--- + +Server Dependency + +```text +Not Allowed +``` + +--- + +Database + +```text +Not Allowed +``` + +--- + +Authentication + +```text +Not Allowed +``` + +--- + +User Accounts + +```text +Not Allowed +``` + +--- + +Dynamic User State + +```text +Not Allowed +``` + +--- + +## SUCCESS CRITERIA + +```text +Workflow Published + +Prompts Published + +Documents Published + +Tools Published + +Showcase Published + +FAQ Published + +GitHub Pages Deployment Works + +Search Works + +New Content Can Be Added Through MDX +``` + +--- + +## FINAL + +REPL Works Website is a Documentation Platform. + +Every implementation must support: + +```text +Documentation + +Discoverability + +Static Deployment + +Long-Term Maintainability + +REPL Works Adoption +``` +`````` diff --git a/src/content/documents/example-ideas-md.mdx b/src/content/documents/example-ideas-md.mdx new file mode 100644 index 0000000..163aacd --- /dev/null +++ b/src/content/documents/example-ideas-md.mdx @@ -0,0 +1,513 @@ +--- +title: 'IDEAS.md 예시' +version: 'v1' +description: '아이디어 정제 Prompt로 만든 IDEAS.md 예시입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# IDEAS.md + +Version 4.0 + +--- + +# Project + +REPL Works + +REPL Works is an AI-Native Product Development Framework +that separates thinking from execution, +keeps project knowledge in living documents, +and maintains project continuity across humans, sessions, and models. + +--- + +# Vision + +REPL Works는 AI 시대를 위한 Product Lifecycle System이다. + +AI는 점점 더 강력해지고 있다. + +더 긴 Context Window. + +더 강력한 Agent. + +더 높은 코드 생성 능력. + +더 빠른 구현 속도. + +--- + +그러나 제품 개발은 여전히 같은 문제를 반복한다. + +좋은 아이디어가 실행으로 이어지지 않는다. + +프로젝트 의도가 사라진다. + +아키텍처가 드리프트한다. + +문서는 오래될수록 신뢰를 잃는다. + +운영 과정에서 발생한 학습이 축적되지 않는다. + +모델을 교체하면 생산성이 초기화된다. + +--- + +REPL Works는 이 문제의 원인이 AI의 지능 부족이 아니라고 믿는다. + +문제는 프로젝트 연속성(Project Continuity)에 있다. + +--- + +# Problem + +현재 대부분의 AI 개발은 Session 중심으로 이루어진다. + +--- + +프로젝트 지식은 다음 위치에 흩어진다. + +* Chat History +* Prompt +* Context Window +* Agent Runtime +* 개인 메모 +* 운영 경험 + +--- + +프로젝트는 수개월 또는 수년 동안 존재할 수 있다. + +그러나 AI 세션은 짧다. + +사람도 바뀐다. + +모델도 바뀐다. + +--- + +결과적으로 다음 문제가 발생한다. + +* 프로젝트 의도가 유지되지 않는다. +* 동일한 실수를 반복한다. +* 중요한 의사결정이 소실된다. +* 아키텍처가 드리프트한다. +* 운영 경험이 축적되지 않는다. +* 프로젝트가 특정 사람 또는 특정 세션에 종속된다. + +--- + +우리는 이 문제를 + +Project Discontinuity + +라고 부른다. + +--- + +# Core Insight + +Projects outlive humans, sessions, and models. + +--- + +AI는 계속 발전한다. + +사람은 팀을 이동한다. + +모델은 교체된다. + +세션은 종료된다. + +--- + +그러나 프로젝트는 계속 살아남아야 한다. + +--- + +프로젝트는 특정 사람의 기억에 의존해서는 안 된다. + +프로젝트는 특정 AI 모델에 의존해서도 안 된다. + +--- + +프로젝트는 스스로를 설명할 수 있어야 한다. + +--- + +# Solution + +REPL Works는 프로젝트의 현재 상태를 유지하기 위한 Living Documents를 제공한다. + +--- + +Idea Phase + +```text +IDEAS.md + +PITCHING_SCRIPT.md +``` + +--- + +Specification Phase + +```text +PRODUCT_SPEC.md +``` + +--- + +Architecture Phase + +```text +ARCHITECTURE.md + +FRAMEWORK.md +``` + +--- + +Planning Phase + +```text +TASKS.md +``` + +--- + +Execution Phase + +```text +AGENTS.md + +Implementation +``` + +--- + +Review Phase + +```text +Issue + +Pull Request + +Architecture Revision + +Task Revision +``` + +--- + +Operation Phase + +```text +Customer Feedback + +Product Improvement + +Specification Update + +Architecture Update + +Task Update +``` + +--- + +프로젝트는 출시로 끝나지 않는다. + +운영 과정에서 학습한 내용은 다시 프로젝트에 반영되어야 한다. + +--- + +# Living Documents + +REPL Works는 문서를 산출물이 아니라 현재 상태의 표현으로 본다. + +--- + +PRODUCT_SPEC.md는 현재 제품을 설명한다. + +ARCHITECTURE.md는 현재 아키텍처를 설명한다. + +TASKS.md는 현재 작업 상태를 설명한다. + +--- + +문서는 버전별로 보관하지 않는다. + +Git이 버전을 관리한다. + +문서는 현재를 설명한다. + +Git은 과거를 보존한다. + +--- + +프로젝트를 이해하기 위해 오래된 문서를 찾을 필요가 없어야 한다. + +--- + +# Development Model + +Thinking LLM + +```text +Ideas + +Product Design + +Architecture + +Planning +``` + +--- + +Execution LLM + +```text +Implementation + +Refactoring + +Testing + +Documentation +``` + +--- + +Thinking과 Execution은 분리된다. + +--- + +Execution은 설계를 검증할 수 있다. + +그러나 설계를 대체하지 않는다. + +--- + +설계 변경이 필요하면 문서를 수정한다. + +문서를 수정한 뒤 구현한다. + +--- + +# Feedback Loop + +REPL Works는 Closed Loop Development를 지향한다. + +--- + +```text +Idea + +↓ + +Specification + +↓ + +Architecture + +↓ + +Tasks + +↓ + +Execution + +↓ + +Review + +↓ + +Operation + +↓ + +Issue + +↓ + +Specification Update + +↓ + +Architecture Update + +↓ + +Tasks Update + +↓ + +Execution +``` + +--- + +모든 개선은 다시 프로젝트 지식으로 환원된다. + +--- + +운영은 개발의 종료가 아니라 다음 개발의 시작이다. + +--- + +# Key Principles + +## Thinking ≠ Execution + +설계와 구현은 분리되어야 한다. + +--- + +## Living Documents + +문서는 항상 현재 상태를 표현해야 한다. + +--- + +## Architecture First + +모든 구현은 Architecture를 따른다. + +--- + +## Tasks Drive Development + +개발은 정의된 작업 범위를 따라야 한다. + +--- + +## Git First + +모든 프로젝트는 Git으로 관리된다. + +--- + +## Closed Feedback Loop + +모든 구현 결과와 운영 결과는 다시 설계로 돌아가야 한다. + +--- + +## Model Independence + +모델은 교체 가능해야 한다. + +--- + +## Project Continuity + +프로젝트는 사람, 세션, 모델보다 오래 살아야 한다. + +--- + +# Target Audience + +### Solo Founder + +### Indie Hacker + +### Small Team + +### AI-Native Builder + +--- + +# Long-Term Goal + +REPL Works를 AI 시대의 Product Lifecycle Standard로 만든다. + +--- + +예를 들어 + +```text +Built with REPL Works +``` + +가 자연스럽게 사용되는 상태를 목표로 한다. + +--- + +REPL Works 프로젝트는 + +누가 개발하더라도, + +어떤 AI를 사용하더라도, + +어떤 시점에 참여하더라도, + +프로젝트를 이해하고 이어갈 수 있어야 한다. + +--- + +# Success Metrics + +### Phase 1 + +REPL Works 자체를 REPL Works로 개발 + +--- + +### Phase 2 + +실제 서비스 5개 이상 운영 + +--- + +### Phase 3 + +외부 사용자가 REPL Works를 사용 + +--- + +### Phase 4 + +REPL Works Compatible 프로젝트 등장 + +--- + +# Final Statement + +AI는 계속 발전한다. + +사람은 바뀐다. + +모델은 교체된다. + +세션은 종료된다. + +--- + +프로젝트는 그보다 오래 살아야 한다. + +--- + +프로젝트는 기억되는 것이 아니라 + +계속 이해될 수 있어야 한다. + +--- + +AI memory is temporary. + +Project continuity must be preserved. + +--- + +Models forget. + +Projects must continue. +`````` diff --git a/src/content/documents/example-pitching-script.mdx b/src/content/documents/example-pitching-script.mdx new file mode 100644 index 0000000..2e0c0a7 --- /dev/null +++ b/src/content/documents/example-pitching-script.mdx @@ -0,0 +1,370 @@ +--- +title: 'PITCHING_SCRIPT.md 예시' +version: 'v1' +description: '피치 작성 Prompt로 만든 PITCHING_SCRIPT.md 예시입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# PITCHING_SCRIPT.md + +Version 3.0 + +--- + +# What Is REPL Works? + +REPL Works는 AI 시대를 위한 Product Development Framework이다. + +--- + +AI는 점점 더 강력해지고 있다. + +더 긴 Context Window. + +더 강력한 Agent. + +더 높은 코드 생성 능력. + +--- + +그러나 제품 개발은 여전히 어렵다. + +--- + +좋은 아이디어는 사라진다. + +설계 의도는 잊혀진다. + +문서는 오래될수록 신뢰를 잃는다. + +아키텍처는 드리프트한다. + +운영 경험은 축적되지 않는다. + +--- + +AI는 발전하고 있지만 + +프로젝트는 여전히 연속성을 잃는다. + +--- + +# The Real Problem + +대부분의 사람들은 AI 개발의 문제를 + +AI의 능력 부족이라고 생각한다. + +--- + +더 좋은 모델. + +더 긴 Context. + +더 강력한 Agent. + +--- + +그러나 REPL Works는 다르게 생각한다. + +--- + +문제는 지능이 아니다. + +문제는 Continuity다. + +--- + +프로젝트는 사람보다 오래 살아야 한다. + +프로젝트는 세션보다 오래 살아야 한다. + +프로젝트는 모델보다 오래 살아야 한다. + +--- + +# Project Continuity + +프로젝트는 계속 이해될 수 있어야 한다. + +--- + +누가 참여하든 + +어떤 모델을 사용하든 + +언제 프로젝트에 합류하든 + +--- + +프로젝트를 이해하고 + +이어서 개발할 수 있어야 한다. + +--- + +그러나 현실은 그렇지 않다. + +--- + +프로젝트 지식은 다음 위치에 흩어진다. + +* Chat History +* Prompt +* Context Window +* Agent Runtime +* 개인 메모 + +--- + +결국 중요한 의사결정은 사라진다. + +--- + +우리는 이 문제를 + +Project Discontinuity + +라고 부른다. + +--- + +# The REPL Works Approach + +REPL Works는 프로젝트 지식을 Living Documents로 관리한다. + +--- + +Idea + +```text +IDEAS.md + +PITCHING_SCRIPT.md +``` + +--- + +Product + +```text +PRODUCT_SPEC.md +``` + +--- + +Architecture + +```text +ARCHITECTURE.md + +FRAMEWORK.md +``` + +--- + +Planning + +```text +TASKS.md +``` + +--- + +Execution + +```text +AGENTS.md +``` + +--- + +이 문서들은 프로젝트의 현재 상태를 설명한다. + +--- + +문서는 버전별로 관리하지 않는다. + +Git이 버전을 관리한다. + +--- + +문서는 현재를 설명한다. + +Git은 과거를 보존한다. + +--- + +# Thinking ≠ Execution + +REPL Works는 설계와 구현을 분리한다. + +--- + +Thinking LLM + +```text +Ideas + +Product Design + +Architecture + +Planning +``` + +--- + +Execution LLM + +```text +Implementation + +Testing + +Refactoring + +Documentation +``` + +--- + +Execution은 Thinking을 대체하지 않는다. + +--- + +설계가 바뀌면 + +문서를 수정한다. + +--- + +문서를 수정한 뒤 + +구현한다. + +--- + +# Development Never Ends + +대부분의 개발 프로세스는 + +출시를 목표로 한다. + +--- + +REPL Works는 운영까지 포함한다. + +--- + +```text +Idea + +↓ + +Specification + +↓ + +Architecture + +↓ + +Tasks + +↓ + +Execution + +↓ + +Release + +↓ + +Operation + +↓ + +Improvement + +↓ + +Specification Update + +↓ + +Architecture Update + +↓ + +Tasks Update +``` + +--- + +운영 결과는 다시 설계로 돌아간다. + +--- + +모든 개선은 프로젝트 지식으로 환원된다. + +--- + +# Why It Matters + +AI는 계속 발전할 것이다. + +사람은 팀을 이동할 것이다. + +모델은 교체될 것이다. + +세션은 종료될 것이다. + +--- + +그러나 프로젝트는 계속 살아남아야 한다. + +--- + +프로젝트는 특정 사람에게 종속되어서는 안 된다. + +프로젝트는 특정 모델에 종속되어서도 안 된다. + +--- + +프로젝트는 스스로를 설명할 수 있어야 한다. + +--- + +# One Sentence + +REPL Works keeps projects understandable, maintainable, and improvable across humans, sessions, and AI models. + +--- + +# Closing + +AI will change. + +Models will change. + +Teams will change. + +--- + +Projects must continue. + +--- + +AI memory is temporary. + +Project continuity must be preserved. + +--- + +Models forget. + +Projects continue. +`````` diff --git a/src/content/documents/example-product-spec.mdx b/src/content/documents/example-product-spec.mdx new file mode 100644 index 0000000..87a3bfd --- /dev/null +++ b/src/content/documents/example-product-spec.mdx @@ -0,0 +1,10 @@ +--- +title: 'PRODUCT_SPEC.md 예시' +version: 'v1' +description: '제품 명세 Prompt로 만든 PRODUCT_SPEC.md 예시입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +준비 중... +`````` diff --git a/src/content/documents/example-tasks.mdx b/src/content/documents/example-tasks.mdx new file mode 100644 index 0000000..21ff73a --- /dev/null +++ b/src/content/documents/example-tasks.mdx @@ -0,0 +1,259 @@ +--- +title: 'TASKS.md 예시' +version: 'v1' +description: '제품 명세 Prompt로 만든 TASKS.md 예시입니다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# TASKS.md + +Version 4.0 + +## PURPOSE + +Current Work Scope + +--- + +ARCHITECTURE.md + +```text +Destination +``` + +TASKS.md + +```text +Current Position +``` + +--- + +Only incomplete tasks may be implemented. + +--- + +Work outside TASKS.md is prohibited. + +--- + +## EXECUTION RULES + +```text +One Prompt += +One Task +``` + +--- + +```text +One Task += +One Commit +``` + +--- + +Do not: + +```text +Combine Tasks + +Implement Future Tasks + +Expand Scope + +Add Unplanned Features +``` + +--- + +If required work is missing: + +```text +STOP + +Propose TASK update +``` + +--- + +# PHASE 1 + +## FOUNDATION + +* [x] T001 Initialize Astro Project +* [x] T002 Configure Tailwind CSS +* [x] T003 Configure Content Collections +* [x] T004 Configure MDX Support +* [x] T005 Configure GitHub Pages Deployment +* [x] T006 Configure Linting and Formatting +* [x] T007 Configure Testing + +--- + +# PHASE 2 + +## PLATFORM FOUNDATION + +* [x] T101 Create Site Shell +* [x] T102 Configure Navigation +* [x] T103 Configure Layout System +* [x] T104 Configure Content Rendering +* [x] T105 Configure Search Infrastructure + +--- + +# PHASE 3 + +## INITIAL WEBSITE RELEASE + +* [x] T201 Create Home Page +* [x] T202 Publish Why Content +* [x] T203 Publish Manifesto +* [x] T204 Publish Specification +* [x] T205 Publish Workflow +* [x] T206 Publish Resources +* [x] T207 Publish Showcase +* [x] T208 Publish FAQ + +--- + +# PHASE 4 + +## REPL WORKS REPOSITIONING + +### INFORMATION ARCHITECTURE + +* [x] T401 Replace legacy navigation with new navigation structure +* [x] T402 Remove Why section +* [x] T403 Remove Manifesto section +* [x] T404 Remove Specification section + +--- + +### HOME + +* [x] T405 Rewrite Home page for AI-Native Product Development Framework positioning +* [x] T406 Add workflow-first messaging +* [x] T407 Add REPL Works Compatible positioning +* [x] T408 Add GitHub call-to-action + +--- + +### WORKFLOW + +* [x] T409 Rewrite Workflow documentation +* [x] T410 Publish current REPL Works workflow +* [x] T411 Explain Planning AI vs Execution AI +* [x] T412 Explain continuous improvement workflow + +--- + +### PROMPTS + +* [x] T413 Create Prompts section +* [x] T414 Publish IDEAS prompt +* [x] T415 Publish PITCHING_SCRIPT prompt +* [x] T416 Publish PRODUCT_SPEC prompt +* [x] T417 Publish ARCHITECTURE prompt +* [x] T418 Publish TASKS prompt +* [x] T419 Publish Review prompts + +--- + +### DOCUMENTS + +* [x] T420 Create Documents section +* [x] T421 Publish AGENTS.md standard +* [x] T422 Publish PRODUCT_SPEC.md standard +* [x] T423 Publish ARCHITECTURE.md standard +* [x] T424 Publish TASKS.md standard + +--- + +### TOOLS + +* [x] T425 Create Tools section +* [x] T426 Publish ai-issue +* [x] T427 Add installation guide +* [x] T428 Add GitHub repository links + +--- + +### SHOWCASE + +* [x] T429 Convert Showcase to REPL Works Compatible Projects +* [x] T430 Publish REPL Works Website showcase +* [x] T431 Publish ai-issue showcase +* [x] T432 Publish Wifi Note showcase + +--- + +### FAQ + +* [x] T433 Rewrite FAQ for framework positioning +* [x] T434 Add compatibility questions +* [x] T435 Add workflow questions +* [x] T436 Add planning vs execution questions + +--- + +# PHASE 5 + +## SEARCH + +* [ ] T501 Verify search indexing for Prompts +* [ ] T502 Verify search indexing for Documents +* [ ] T503 Verify search indexing for Tools +* [ ] T504 Verify search indexing for Showcase +* [ ] T505 Verify search indexing for FAQ + +--- + +# PHASE 6 + +## CONTENT REVIEW + +* [ ] T601 Review Workflow content +* [ ] T602 Review Prompt content +* [ ] T603 Review Document content +* [ ] T604 Review Tool content +* [ ] T605 Review Showcase content + +--- + +# PHASE 7 + +## RELEASE + +* [ ] T701 Responsive Review +* [ ] T702 Accessibility Review +* [ ] T703 Search Verification +* [ ] T704 GitHub Pages Verification +* [ ] T705 Release v2 + +--- + +## COMPLETION + +```text +[ ] +↓ +[x] +``` + +--- + +After task completion: + +Review ARCHITECTURE.md + +--- + +If architecture changed: + +Update ARCHITECTURE.md +`````` diff --git a/src/content/documents/framework.mdx b/src/content/documents/framework.mdx new file mode 100644 index 0000000..12d332e --- /dev/null +++ b/src/content/documents/framework.mdx @@ -0,0 +1,195 @@ +--- +title: 'FRAMEWORK.md' +version: 'v1' +description: 'FRAMEWORK.md는 기술 스택별 구현 규칙을 정의하는 문서다.' +publishedAt: '2026-06-12T00:00:00Z' +--- + +이 문서의 목적은 프로젝트 구조를 정의하는 것이 아니다. + +선택된 기술 스택을 일관되게 사용하는 방법을 정의하는 것이다. + +--- + +# Purpose + +다음 질문에 답한다. + +```text +이 기술 스택은 어떻게 사용해야 하는가? + +파일은 어디에 위치해야 하는가? + +어떤 구현 규칙을 따라야 하는가? + +무엇을 허용하고 무엇을 금지하는가? +``` + +--- + +FRAMEWORK.md는 기술 스택에 대한 구현 가이드다. + +--- + +# Inputs + +일반적으로 다음 정보를 기반으로 작성한다. + +- ARCHITECTURE.md +- 선택된 기술 스택 +- 프로젝트 구조 +- 조직의 개발 규칙 +- 운영 경험 + +--- + +# Outputs + +다음 내용을 정의한다. + +- 프로젝트 구조 규칙 +- 파일 배치 규칙 +- 라우팅 규칙 +- 컴포넌트 규칙 +- 데이터 규칙 +- 스타일링 규칙 +- 성능 규칙 +- 생성 규칙 +- 네이밍 규칙 + +--- + +# Lifecycle + +프로젝트 초기 단계에 생성한다. + +--- + +일반적으로 기술 스택이 변경되지 않는 한 자주 수정되지 않는다. + +--- + +기술 스택 변경 또는 운영 경험 축적 시 업데이트할 수 있다. + +--- + +# Relationship + +```text +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +TASKS.md +↓ +AGENTS.md +``` + +--- + +ARCHITECTURE.md는 프로젝트 구조를 정의한다. + +--- + +FRAMEWORK.md는 해당 구조를 구현하는 규칙을 정의한다. + +--- + +TASKS.md는 이 규칙을 기반으로 작업을 수행한다. + +--- + +# AI Usage + +Execution AI가 반드시 읽어야 하는 문서다. + +--- + +Planning AI는 필요 시 참고할 수 있다. + +--- + +구현 규칙에 대한 최종 기준은 FRAMEWORK.md다. + +--- + +# Examples + +REPL Works는 기술 스택별 FRAMEWORK.md를 사용할 수 있다. + +예시: + +```text +ASTRO.md + +NEXTJS.md + +GO.md + +FASTAPI.md + +REACT.md +``` + +--- + +각 문서는 해당 기술 스택의 권장 구조와 구현 규칙을 정의한다. + +--- + +# Generate With + +FRAMEWORK.md는 ReplWorks에서 제공하며, 제공하는 프레임워크는 다음과 같다. + +- [ASTRO.md](/frameworks/astro) +- [FASTAPI.md](/frameworks/fastapi) +- [GOLANG-CLI.md](/frameworks/golang-cli) +- [NEXTJS.md](/frameworks/nextjs) +- [REACT_VITE.md](/frameworks/react-vite) +- [VANILLA.md](/frameworks/vanilla) + +--- + +프로젝트마다 새로 만드는 것이 아니라, + +검증된 기술 스택 규칙을 재사용하는 경우가 많다. + +--- + +조직 또는 개인은 자체 FRAMEWORK.md 라이브러리를 구축할 수 있다. + +--- + +# Key Principle + +좋은 FRAMEWORK.md는 기능을 설명하지 않는다. + +좋은 FRAMEWORK.md는 구현 규칙을 설명한다. + +--- + +# Why It Matters + +프로젝트는 바뀔 수 있다. + +기능도 바뀔 수 있다. + +--- + +하지만 기술 스택 사용 규칙은 일관되어야 한다. + +--- + +FRAMEWORK.md는 AI가 기술 스택을 예측하지 않도록 만든다. + +--- + +프로젝트 구조는 ARCHITECTURE.md에 저장된다. + +구현 규칙은 FRAMEWORK.md에 저장된다. + +--- + +둘은 서로를 대체하지 않는다. diff --git a/src/content/documents/ideas.mdx b/src/content/documents/ideas.mdx index 3862557..36b5bee 100644 --- a/src/content/documents/ideas.mdx +++ b/src/content/documents/ideas.mdx @@ -1,30 +1,148 @@ --- title: 'IDEAS.md' version: 'v1' -description: 'Idea refinement record for project discovery and validation.' +description: 'IDEAS.md는 프로젝트 아이디어를 검증하고 정제하기 위한 문서다.' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +이 문서의 목적은 무엇을 만들지 결정하는 것이 아니다. -Capture refined project ideas before specification work begins. +무엇을 만들 가치가 있는지 판단하는 것이다. -## Inputs +--- + +# Purpose + +아이디어를 사업적 관점에서 검토한다. + +--- + +다음을 검증한다. + +```text +문제가 충분히 중요한가? + +누가 이 문제를 가지고 있는가? + +기존 대안은 무엇인가? + +차별성은 존재하는가? + +장기적으로 유지 가능한가? +``` + +--- + +# Inputs + +일반적으로 다음 정보를 기반으로 작성한다. + +- 초기 아이디어 +- 사용자 불편 +- 시장 관찰 +- 경쟁 제품 분석 +- 개인 경험 +- 사업 가설 + +--- + +# Outputs + +다음 내용을 정리한다. + +- 문제 정의 +- 대상 사용자 +- 제안하는 방향 +- 차별성 +- 위험 요소 +- 제약 사항 +- 검증이 필요한 항목 + +--- + +# Lifecycle + +프로젝트 초기 단계에서 생성한다. + +--- + +IDEAS.md는 아이디어가 충분히 검증될 때까지 반복적으로 수정한다. + +--- + +아이디어 검증이 완료되면 PITCHING_SCRIPT.md 작성 단계로 이동한다. + +--- + +# Relationship + +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +``` + +--- + +IDEAS.md는 프로젝트의 출발점이다. + +--- + +# AI Usage + +IDEAS.md는 주로 Planning AI와 사람이 함께 사용하는 문서다. + +--- + +Execution AI가 반드시 읽어야 하는 문서는 아니다. + +--- + +프로젝트가 진행되면서 핵심 내용은 이후 문서로 전달된다. -- raw ideas -- market observations -- user pain points +--- + +# Generate With + +IDEAS.md는 일반적으로 다음 프롬프트를 통해 생성한다. + +→ [아이디어 정제 Prompt](/prompts/idea-refinement) + +--- + +아이디어 정제 Prompt는 다음을 수행한다. + +- 아이디어 검증 +- 시장성 검토 +- 사용자 분석 +- 위험 요소 식별 +- 장기 지속 가능성 평가 -## Outputs +--- + +# Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 IDEAS.md 작성 방식을 확인할 수 있다. + +→ [Example IDEAS.md](./example-ideas-md) -- validated direction -- risks -- open questions +--- + +예시는 다음 내용을 포함한다. -## Lifecycle +- 문제 정의 +- 대상 사용자 +- 제안 방향 +- 핵심 가설 +- 위험 요소 +- 검증 결과 + +--- -Created during discovery and updated until the idea is ready for pitching. +# Key Principle -## Relationships +좋은 IDEAS.md는 아이디어를 설명하지 않는다. -Feeds `PITCHING_SCRIPT.md` and informs `PRODUCT_SPEC.md`. +좋은 IDEAS.md는 아이디어를 검증한다. diff --git a/src/content/documents/index.mdx b/src/content/documents/index.mdx index 996606d..d0fdbae 100644 --- a/src/content/documents/index.mdx +++ b/src/content/documents/index.mdx @@ -1,23 +1,310 @@ --- title: 'Documents' version: 'v1' -description: 'Reusable document standards for the REPL Works framework.' +description: 'Document standards used by the REPL Works framework.' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +REPL Works는 문서를 단순한 기록으로 보지 않는다. -Document the standards that keep REPL Works projects consistent over time. +문서는 프로젝트 기억(Project Memory)의 일부이다. -## Documents +--- + +프로젝트는 수개월 또는 수년 동안 유지된다. + +세션은 몇 시간 또는 몇 주 안에 종료된다. + +--- + +REPL Works는 프로젝트 기억을 문서와 Git에 저장한다. + +이를 통해 모델이 바뀌어도 프로젝트를 이어갈 수 있다. + +--- + +# Document Flow + +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +TASKS.md +↓ +AGENTS.md +``` + +--- + +각 문서는 서로 다른 책임을 가진다. + +문서는 서로를 대체하지 않는다. + +--- + +# IDEAS.md + +아이디어를 검증하고 정제한다. + +--- + +목적 + +```text +Should we build this? +``` + +--- + +주요 내용 + +- 문제 정의 +- 대상 사용자 +- 시장성 +- 위험 요소 +- 제약 사항 + +--- + +[View Document Standard](/documents/ideas) + +--- + +# PITCHING_SCRIPT.md + +프로젝트를 설명한다. + +--- + +목적 + +```text +Why does this project exist? +``` + +--- + +주요 내용 + +- 프로젝트 정의 +- 핵심 가치 +- 차별성 +- 비전 + +--- + +[View Document Standard](/documents/pitching-script) + +--- + +# PRODUCT_SPEC.md + +제품 요구사항을 정의한다. + +--- + +목적 + +```text +What should be built? +``` + +--- + +주요 내용 + +- 제품 정의 +- 사용자 여정 +- 정보 구조 +- 범위 +- 성공 기준 + +--- + +[View Document Standard](/documents/product-spec) + +--- + +# ARCHITECTURE.md + +기술 구조를 정의한다. + +--- + +목적 + +```text +How should it be built? +``` + +--- + +주요 내용 + +- 시스템 구조 +- 콘텐츠 구조 +- 모듈 구조 +- 제약 사항 +- 운영 구조 + +--- + +ARCHITECTURE.md는 프로젝트의 기술적 진실이다. + +--- + +[View Document Standard](/documents/architecture) + +--- + +# FRAMEWORK.md + +기술 스택별 구현 규칙을 정의한다. -- [AGENTS.md](/documents/agents) -- [PITCHING_SCRIPT.md](/documents/pitching-script) -- [PRODUCT_SPEC.md](/documents/product-spec) -- [ARCHITECTURE.md](/documents/architecture) -- [TASKS.md](/documents/tasks) -- [IDEAS.md](/documents/ideas) +--- + +목적 + +```text +How should this stack be used? +``` + +--- + +주요 내용 + +- 프로젝트 구조 +- 파일 배치 규칙 +- 라우팅 규칙 +- 컴포넌트 규칙 +- 스타일링 규칙 +- 성능 규칙 +- 생성 규칙 + +--- + +FRAMEWORK.md는 기술 스택에 대한 구현 가이드다. + +--- + +ARCHITECTURE.md가 프로젝트 구조를 설명한다면, + +FRAMEWORK.md는 해당 구조를 구현하는 방법을 설명한다. + +--- + +[View Document Standard](/documents/framework) + +--- + +# TASKS.md + +현재 작업 상태를 정의한다. + +--- + +목적 + +```text +What should be done next? +``` + +--- + +주요 내용 + +- 작업 목록 +- 진행 상태 +- 현재 우선순위 + +--- + +TASKS.md는 현재 위치를 설명한다. + +--- + +[View Document Standard](/documents/tasks) + +--- + +# AGENTS.md + +AI 작업 규칙을 정의한다. + +--- + +목적 + +```text +How should AI work? +``` + +--- + +주요 내용 + +- 문서 읽기 순서 +- 구현 규칙 +- 범위 제어 +- 작업 절차 + +--- + +AGENTS.md는 모든 AI의 진입점이다. + +--- + +[View Document Standard](/documents/agents) + +--- + +# Living Documents + +REPL Works 문서는 버전 문서가 아니다. + +--- + +문서는 항상 현재 상태를 설명해야 한다. + +--- + +제품이 운영 단계에 진입한 이후에도 계속 갱신된다. + +--- + +과거 상태는 Git이 보존한다. + +현재 상태는 문서가 설명한다. + +--- + +# 핵심 원칙 + +## Project Memory + +문서는 프로젝트 기억이다. + +--- + +## Git-Native + +문서는 Git과 함께 관리된다. + +--- + +## Living Documentation + +문서는 최신 상태를 유지한다. + +--- -## Lifecycle +## Model Independent -Each document captures a different stage of the project lifecycle and is updated only when its responsibility changes. +어떤 AI라도 문서를 읽고 프로젝트를 이해할 수 있어야 한다. diff --git a/src/content/documents/pitching-script.mdx b/src/content/documents/pitching-script.mdx index 7ce9d99..ed414f4 100644 --- a/src/content/documents/pitching-script.mdx +++ b/src/content/documents/pitching-script.mdx @@ -1,30 +1,144 @@ --- title: 'PITCHING_SCRIPT.md' version: 'v1' -description: 'Pitch document that turns a refined idea into a concise narrative.' +description: 'PITCHING_SCRIPT.md는 프로젝트의 존재 이유를 설명하는 문서다.' publishedAt: '2026-06-12T00:00:00Z' --- +이 문서의 목적은 제품 요구사항을 정의하는 것이 아니다. + +프로젝트를 이해시키는 것이다. + +--- + ## Purpose -Turn refined ideas into a clear pitch that can be reviewed and reused. +프로젝트를 처음 접하는 사람에게 다음 질문에 답한다. + +```text +이 프로젝트는 무엇인가? + +왜 존재하는가? + +누구를 위한 것인가? + +왜 중요한가? +``` + +--- + +PITCHING_SCRIPT.md는 프로젝트의 핵심 메시지를 정리한다. + +--- ## Inputs -- `IDEAS.md` -- target audience -- problem definition +일반적으로 다음 정보를 기반으로 작성한다. + +- IDEAS.md +- 문제 정의 +- 대상 사용자 +- 검증된 가설 +- 핵심 가치 + +--- ## Outputs -- project pitch -- positioning -- rationale +다음 내용을 정리한다. + +- 프로젝트 정의 +- 문제 설명 +- 대상 사용자 +- 핵심 가치 +- 차별성 +- 비전 +- 한 문장 요약 + +--- ## Lifecycle -Written after idea refinement and before product specification. +IDEAS.md가 충분히 검증된 이후 작성한다. + +--- + +PRODUCT_SPEC.md를 작성하기 전에 프로젝트 방향을 명확하게 정리한다. + +--- + +프로젝트의 핵심 메시지가 변경될 경우 업데이트할 수 있다. + +--- + +## Relationship + +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +``` + +--- + +PITCHING_SCRIPT.md는 아이디어와 제품 명세 사이를 연결한다. + +--- + +## AI Usage + +PITCHING_SCRIPT.md는 Planning AI와 사람이 함께 사용하는 문서다. + +--- + +Execution AI가 반드시 읽어야 하는 문서는 아니다. + +--- + +핵심 내용은 이후 PRODUCT_SPEC.md에 반영된다. + +--- + +## Generate With + +PITCHING_SCRIPT.md는 일반적으로 다음 프롬프트를 통해 생성한다. + +→ [피치 작성 Prompt](/prompts/pitch-creation) + +--- + +피치 작성 Prompt는 다음을 수행한다. + +- 프로젝트 정의 정리 +- 문제 설명 정리 +- 핵심 가치 도출 +- 차별성 정리 +- 프로젝트 메시지 명확화 + +--- + +## Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 PITCHING_SCRIPT.md 작성 방식을 확인할 수 있다. + +→ [Example PITCHING_SCRIPT.md](./example-pitching-script) + +--- + +예시는 다음 내용을 포함한다. + +- 프로젝트 소개 +- 문제 정의 +- 핵심 가치 +- 비전 +- 한 문장 설명 + +--- + +## Key Principle -## Relationships +좋은 PITCHING_SCRIPT.md는 제품을 설명하지 않는다. -Sits between `IDEAS.md` and `PRODUCT_SPEC.md`. +좋은 PITCHING_SCRIPT.md는 프로젝트가 왜 존재하는지 설명한다. diff --git a/src/content/documents/product-spec.mdx b/src/content/documents/product-spec.mdx index 557e740..111ec97 100644 --- a/src/content/documents/product-spec.mdx +++ b/src/content/documents/product-spec.mdx @@ -1,30 +1,164 @@ --- title: 'PRODUCT_SPEC.md' version: 'v1' -description: 'Product source of truth for the website and framework.' +description: 'PRODUCT_SPEC.md는 제품의 진실(Source of Truth)이다.' publishedAt: '2026-06-12T00:00:00Z' --- -## Purpose +이 문서의 목적은 기술 구조를 정의하는 것이 아니다. -Define the product, users, journey, UX, content, and business intent. +무엇을 만들어야 하는지 정의하는 것이다. -## Inputs +--- + +# Purpose + +다음 질문에 답한다. + +```text +무엇을 만들 것인가? + +누구를 위한 것인가? + +왜 중요한가? + +사용자는 무엇을 경험해야 하는가? +``` + +--- + +PRODUCT_SPEC.md는 제품 관점의 기준 문서다. + +--- + +# Inputs + +일반적으로 다음 정보를 기반으로 작성한다. + +- PITCHING_SCRIPT.md +- 사용자 요구사항 +- 비즈니스 목표 +- 시장 이해 +- 프로젝트 방향성 + +--- + +# Outputs + +다음 내용을 정의한다. + +- 제품 정의 +- 대상 사용자 +- 핵심 가치 +- 핵심 메시지 +- 사용자 여정 +- 정보 구조 +- 화면 또는 페이지 역할 +- 기능 범위 +- 제외 범위 +- 성공 기준 + +--- + +# Lifecycle + +PITCHING_SCRIPT.md 이후 작성한다. + +--- + +제품의 의미가 변경될 때 업데이트한다. + +--- + +사용자 경험이 변경될 경우 업데이트한다. + +--- + +기능 추가만으로는 반드시 수정할 필요는 없다. + +--- + +# Relationship -- pitch -- user needs -- business goals +```text +IDEAS.md +↓ +PITCHING_SCRIPT.md +↓ +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +TASKS.md +``` -## Outputs +--- + +PRODUCT_SPEC.md는 기술 구현보다 우선한다. + +--- + +ARCHITECTURE.md는 PRODUCT_SPEC.md를 구현하기 위해 존재한다. + +--- + +TASKS.md는 PRODUCT_SPEC.md를 실현하기 위해 존재한다. + +--- + +# AI Usage + +Planning AI가 반드시 읽어야 하는 문서다. + +--- + +Execution AI도 반드시 읽어야 하는 문서다. + +--- + +제품 요구사항에 대한 최종 기준은 PRODUCT_SPEC.md다. -- product definition -- page responsibilities -- information architecture +--- + +# Generate With + +PRODUCT_SPEC.md는 일반적으로 다음 프롬프트를 통해 생성한다. + +→ [제품 명세 Prompt](/prompts/product-specification) + +--- + +제품 명세 Prompt는 다음을 수행한다. + +- 제품 정의 +- 사용자 정의 +- 사용자 여정 설계 +- 정보 구조 설계 +- 범위 정의 +- 성공 기준 정의 + +--- + +# Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 PRODUCT_SPEC.md 작성 방식을 확인할 수 있다. -## Lifecycle +→ [Example PRODUCT_SPEC.md](./example-product-spec) + +--- + +예시는 다음 내용을 포함한다. + +- 제품 정의 +- 사용자 여정 +- 정보 구조 +- 범위 정의 +- 성공 기준 + +--- -Updated when product meaning or user-facing structure changes. +# Key Principle -## Relationships +좋은 PRODUCT_SPEC.md는 구현 방법을 설명하지 않는다. -Guides `ARCHITECTURE.md` and constrains `TASKS.md`. +좋은 PRODUCT_SPEC.md는 무엇을 만들어야 하는지 설명한다. diff --git a/src/content/documents/tasks.mdx b/src/content/documents/tasks.mdx index 071f13f..1895c32 100644 --- a/src/content/documents/tasks.mdx +++ b/src/content/documents/tasks.mdx @@ -1,30 +1,212 @@ --- title: 'TASKS.md' version: 'v1' -description: 'Current work scope and execution order for REPL Works.' +description: 'TASKS.md는 현재 작업 범위를 정의하는 문서다.' publishedAt: '2026-06-12T00:00:00Z' --- +이 문서의 목적은 프로젝트의 현재 위치를 설명하는 것이다. + +--- + ## Purpose -Track the current implementation scope and the order in which work should be done. +다음 질문에 답한다. + +```text +현재 무엇을 해야 하는가? + +어떤 순서로 진행해야 하는가? + +무엇이 완료되었는가? + +무엇이 아직 남아 있는가? +``` + +--- + +TASKS.md는 프로젝트의 현재 상태를 설명한다. + +--- ## Inputs -- `PRODUCT_SPEC.md` -- `ARCHITECTURE.md` -- active project state +일반적으로 다음 정보를 기반으로 작성한다. + +- [PRODUCT_SPEC.md](./product-spec) +- [ARCHITECTURE.md](./architecture) +- [FRAMEWORK.md](./framework) +- 현재 프로젝트 상태 +- 승인된 요구사항 + +--- ## Outputs -- task list -- execution order -- completion status +다음 내용을 정의한다. + +- 작업 목록 +- 우선순위 +- 실행 순서 +- 진행 상태 +- 완료 상태 + +--- ## Lifecycle -Updated as tasks are completed or newly scoped work is approved. +ARCHITECTURE.md 이후 작성한다. + +--- + +작업 완료 시 지속적으로 업데이트한다. + +--- + +새로운 범위가 승인되면 작업을 추가할 수 있다. + +--- + +완료된 작업은 기록으로 유지한다. + +--- + +## Relationship + +```text +PRODUCT_SPEC.md +↓ +ARCHITECTURE.md +↓ +FRAMEWORK.md +↓ +TASKS.md +↓ +Execution +``` + +--- + +PRODUCT_SPEC.md는 목적지를 정의한다. + +--- + +ARCHITECTURE.md는 구조를 정의한다. + +--- + +FRAMEWORK.md는 구현 규칙을 정의한다. + +--- + +TASKS.md는 현재 위치를 정의한다. + +--- + +## AI Usage + +Execution AI가 반드시 읽어야 하는 문서다. + +--- + +작업 범위에 대한 최종 기준은 TASKS.md다. + +--- + +TASKS.md에 없는 작업은 구현해서는 안 된다. -## Relationships +--- + +필요한 작업이 존재하지 않는 경우: + +```text +STOP + +Propose TASKS.md update +``` + +--- + +## Structure + +일반적으로 Phase 기반으로 구성한다. + +예시: + +```text +PHASE 1 + +- [x] Task A +- [x] Task B + +PHASE 2 + +- [ ] Task C +- [ ] Task D +``` + +--- + +각 작업은 명확하고 검증 가능해야 한다. + +--- + +## Generate With + +TASKS.md는 일반적으로 다음 프롬프트를 통해 생성한다. + +→ [Task Generation Prompt](/prompts/task-generation) + +--- + +Task Generation Prompt는 다음을 수행한다. + +- 작업 분해 +- 우선순위 설정 +- Phase 구성 +- 실행 순서 정의 + +--- + +## Example + +실제 REPL Works Compatible 프로젝트 예시를 통해 TASKS.md 작성 방식을 확인할 수 있다. + +→ [Example TASKS.md](./example-tasks) + +--- + +예시는 다음 내용을 포함한다. + +- Phase 구조 +- 작업 목록 +- 진행 상태 +- 완료 기준 + +--- + +## Key Principle + +좋은 TASKS.md는 미래 계획을 설명하지 않는다. + +좋은 TASKS.md는 현재 해야 할 일을 설명한다. + +--- + +## Why It Matters + +AI는 범위를 확장하려는 경향이 있다. + +--- + +TASKS.md는 이를 방지한다. + +--- + +PRODUCT_SPEC.md가 목적지라면, + +TASKS.md는 현재 위치다. + +--- -Must stay aligned with `PRODUCT_SPEC.md` and `ARCHITECTURE.md`. +Execution AI는 현재 위치에서 다음 단계만 수행해야 한다. diff --git a/src/content/frameworks/astro.mdx b/src/content/frameworks/astro.mdx new file mode 100644 index 0000000..c290999 --- /dev/null +++ b/src/content/frameworks/astro.mdx @@ -0,0 +1,311 @@ +--- +title: 'ASTRO.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 ASTRO.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# ASTRO.md + +## STACK + +REQUIRED + +- Astro 6.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- React 19.x +- MDX + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +FRAMEWORK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_ASTRO_VERSION + +DO_NOT_GENERATE_CODE_FOR_OTHER_VERSIONS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +src/ +├── components/ +├── layouts/ +├── pages/ +├── content/ +├── images/ +├── data/ +├── utils/ +└── styles/ + +public/ + +astro.config.mjs +content.config.ts +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +FOLLOW_EXISTING_STRUCTURE_BEFORE_CREATING_NEW_STRUCTURE + +--- + +## FILE_PLACEMENT + +pages -> src/pages + +layouts -> src/layouts + +components -> src/components + +content -> src/content + +images -> src/images + +data -> src/data + +utilities -> src/utils + +styles -> src/styles + +static_assets -> public + +content_configuration -> content.config.ts + +astro_configuration -> astro.config.mjs + +DO_NOT_CREATE_COMPONENTS_OUTSIDE_DEFINED_LOCATIONS + +--- + +## ROUTING_RULES + +USE_FILE_BASED_ROUTING + +ROUTES_BELONG_IN_SRC_PAGES + +DO_NOT_CREATE_CUSTOM_ROUTING_SYSTEM + +FOLLOW_ASTRO_ROUTING_CONVENTIONS + +--- + +## COMPONENT_RULES + +USE_ASTRO_COMPONENTS_BY_DEFAULT + +PREFER_ASTRO_OVER_REACT + +USE_REACT_ONLY_WHEN_REQUIRED + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## CONTENT_RULES + +CONTENT_BELONGS_IN_SRC_CONTENT + +USE_CONTENT_COLLECTIONS + +CONTENT_CONFIG_IS_SOURCE_OF_TRUTH + +DO_NOT_STORE_CONTENT_IN_COMPONENTS + +DO_NOT_STORE_LARGE_CONTENT_BLOCKS_IN_PAGES + +SEPARATE_CONTENT_FROM_PRESENTATION + +--- + +## DATA_RULES + +STATIC_DATA_BELONGS_IN_SRC_DATA + +NAVIGATION_DATA_BELONGS_IN_SRC_DATA + +FAQ_DATA_BELONGS_IN_SRC_DATA + +CONFIGURATION_DATA_BELONGS_IN_SRC_DATA + +DO_NOT_STORE_DATA_IN_COMPONENTS + +SEPARATE_DATA_FROM_PRESENTATION + +--- + +## IMAGE_RULES + +PROJECT_IMAGES_BELONG_IN_SRC_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +USE_ASTRO_IMAGE_OPTIMIZATION_WHEN_AVAILABLE + +DO_NOT_STORE_IMAGES_IN_COMPONENT_DIRECTORIES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +PREFER_GLOBAL_STYLES_IN_SRC_STYLES + +--- + +## PERFORMANCE_RULES + +PREFER_STATIC_GENERATION + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +MINIMIZE_HYDRATION + +LOAD_ONLY_REQUIRED_CLIENT_CODE + +AVOID_UNNECESSARY_REACT_COMPONENTS + +--- + +## ISLAND_RULES + +USE_ISLANDS_ARCHITECTURE + +DEFAULT_TO_SERVER_RENDERED_CONTENT + +HYDRATE_ONLY_WHEN_NECESSARY + +DO_NOT_HYDRATE_STATIC_CONTENT + +USE_CLIENT_DIRECTIVES_ONLY_WHEN_REQUIRED + +--- + +## NAMING_RULES + +COMPONENT_FILES -> PascalCase + +LAYOUT_FILES -> PascalCase + +UTILITY_FILES -> camelCase + +DATA_FILES -> camelCase + +CONTENT_FILES -> kebab-case + +IMAGE_FILES -> kebab-case + +EXAMPLES + +- Header.astro + +- HeroSection.astro + +- PostLayout.astro + +- navigationData.js + +- faqData.js + +- getting-started.md + +- first-blog-post.md + +--- + +## ROOT_DIRECTORY_POLICY + +DO_NOT_CREATE_FILES_IN_REPOSITORY_ROOT + +UNLESS_REQUIRED_BY_ASTRO + +ALLOWED_ROOT_FILES + +- astro.config.mjs +- content.config.ts +- package.json +- README.md +- tsconfig.json + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_CONTENT +4. CHECK_EXISTING_DATA +5. CHECK_EXISTING_PATTERNS +6. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_NEW_FILES + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +DO_NOT_GUESS + +--- + +## ASTRO_PRINCIPLES + +STATIC_FIRST + +CONTENT_FIRST + +SERVER_FIRST + +USE_ISLANDS_ARCHITECTURE + +MINIMIZE_JAVASCRIPT + +HYDRATE_ONLY_WHEN_NECESSARY +`````` diff --git a/src/content/frameworks/fastapi.mdx b/src/content/frameworks/fastapi.mdx new file mode 100644 index 0000000..470ae2c --- /dev/null +++ b/src/content/frameworks/fastapi.mdx @@ -0,0 +1,268 @@ +--- +title: 'FASTAPI.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 FASTAPI.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# FASTAPI.md + +## STACK + +REQUIRED + +- Python 3.13+ +- FastAPI +- Pydantic 2.x +- Uvicorn + +OPTIONAL + +- SQLAlchemy +- Alembic +- PostgreSQL + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PYPROJECT_TOML_IS_SOURCE_OF_TRUTH + +REQUIREMENTS_TXT_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PROJECT_CONFIGURATION + +--- + +## PROJECT_STRUCTURE + +```text +app/ +├── api/ +├── schemas/ +├── dependencies/ +├── core/ +└── main.py + +tests/ + +pyproject.toml +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CONTROLLERS_DIRECTORY + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +api_routes -> app/api + +request_schemas -> app/schemas + +response_schemas -> app/schemas + +shared_dependencies -> app/dependencies + +application_configuration -> app/core + +application_entry -> app/main.py + +tests -> tests + +--- + +## API_RULES + +USE_APIRouter + +GROUP_RELATED_ENDPOINTS + +KEEP_ROUTE_MODULES_SMALL + +KEEP_ENDPOINTS_FOCUSED + +FOLLOW_FASTAPI_CONVENTIONS + +ROUTES_BELONG_IN_APP_API + +--- + +## SCHEMA_RULES + +USE_PYDANTIC_MODELS + +REQUEST_MODELS_ARE_REQUIRED + +RESPONSE_MODELS_ARE_REQUIRED + +SEPARATE_REQUEST_AND_RESPONSE_MODELS_WHEN_NEEDED + +DO_NOT_USE_RAW_DICTIONARIES_FOR_PUBLIC_APIS + +--- + +## DEPENDENCY_RULES + +USE_FASTAPI_DEPENDENCY_INJECTION + +SHARED_DEPENDENCIES_BELONG_IN_APP_DEPENDENCIES + +AVOID_GLOBAL_STATE + +PREFER_EXPLICIT_DEPENDENCIES + +--- + +## CONFIGURATION_RULES + +APPLICATION_CONFIGURATION_BELONGS_IN_APP_CORE + +USE_ENVIRONMENT_VARIABLES_FOR_CONFIGURATION + +DO_NOT_HARDCODE_SECRETS + +DO_NOT_HARDCODE_CREDENTIALS + +DO_NOT_HARDCODE_API_KEYS + +--- + +## DATABASE_RULES + +DATABASE_INTEGRATION_IS_OPTIONAL + +DO_NOT_ASSUME_DATABASE_USAGE + +DO_NOT_ASSUME_DATABASE_ENGINE + +FOLLOW_DECLARED_PROJECT_DEPENDENCIES + +--- + +## TESTING_RULES + +TESTS_BELONG_IN_TESTS_DIRECTORY + +USE_PYTEST + +TEST_API_ENDPOINTS + +TEST_CORE_BUSINESS_BEHAVIOR + +--- + +## ARCHITECTURE_RULES + +DO_NOT_CREATE_SERVICES_DIRECTORY + +DO_NOT_CREATE_REPOSITORIES_DIRECTORY + +DO_NOT_CREATE_CUSTOM_ARCHITECTURE + +DO_NOT_INTRODUCE_PATTERNS_NOT_DEFINED_IN_ARCHITECTURE_MD + +DO_NOT_CREATE_ABSTRACTIONS_WITHOUT_JUSTIFICATION + +PREFER_SIMPLE_OVER_COMPLEX + +--- + +## FORBIDDEN_DIRECTORIES + +- src +- services +- repositories +- controllers + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- tests + +ALLOWED_ROOT_FILES + +- pyproject.toml +- README.md +- .env.example + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PYPROJECT_TOML_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## FASTAPI_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +API_FIRST + +MINIMAL_STRUCTURE + +SCHEMAS_ARE_REQUIRED + +DEPENDENCY_INJECTION_OVER_GLOBAL_STATE + +NO_ARCHITECTURAL_GUESSING + +REUSE_BEFORE_CREATING + +KEEP_IT_SIMPLE +`````` diff --git a/src/content/frameworks/golang-cli.mdx b/src/content/frameworks/golang-cli.mdx new file mode 100644 index 0000000..e48e5c4 --- /dev/null +++ b/src/content/frameworks/golang-cli.mdx @@ -0,0 +1,415 @@ +--- +title: 'GOLANG-CLI.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 GOLANG-CLI.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# GOLANG-CLI.md + +# AI Issue Publisher Framework + +## Purpose + +This document defines implementation constraints. + +PRODUCT_SPEC.md defines what must be built. + +FRAMEWORK.md defines how it must be built. + +Implementations must follow this document exactly. + +Do not replace technologies. + +Do not introduce alternatives. + +Do not redesign architecture. + +--- + +# Language + +Use: + +```text +Go >= 1.24 +``` + +Do not use: + +```text +Node.js +TypeScript +Python +Rust +PHP +Java +``` + +--- + +# Architecture Style + +Use: + +```text +Single Binary CLI +``` + +Requirements: + +- no backend service +- no database +- no web server +- no daemon process + +The application must execute as a standalone command-line tool. + +--- + +# CLI Framework + +Use: + +```text +github.com/spf13/cobra +``` + +Do not introduce additional CLI frameworks. + +--- + +# Clipboard + +Use: + +```text +golang.design/x/clipboard +``` + +Clipboard is the primary input source. + +Do not require file input for normal workflows. + +--- + +# Markdown Processing + +Use: + +```text +github.com/yuin/goldmark +``` + +Markdown must be parsed programmatically. + +Do not use regex-only parsing. + +--- + +# GitHub Integration + +Use: + +```text +GitHub REST API +``` + +Authentication: + +```text +AI_BACKLOG_TOKEN +``` + +Requirements: + +- token belongs to ai-backlog-bot +- issues must be created using ai-backlog-bot credentials +- GitHub must display ai-backlog-bot as issue author + +Do not use: + +```text +Current user credentials +``` + +Do not create issues as the publishing user. + +--- + +# Publisher Detection + +Publisher identity is informational only. + +Resolve publisher using: + +```text +gh api user +``` + +Fallback: + +```text +git config user.name +``` + +Publisher information must be stored inside issue metadata. + +Publisher identity must never be used for issue creation. + +--- + +# Repository Resolution + +Resolve repository from: + +```text +git remote get-url origin +``` + +Expected result: + +```text +owner/repository +``` + +If repository resolution fails: + +```text +abort operation +``` + +Do not request repository information interactively. + +--- + +# Configuration + +Configuration format: + +```text +YAML +``` + +Location: + +```text +~/.config/ai-issue/config.yaml +``` + +Configuration is optional for MVP. + +Environment variables are preferred for secrets. + +--- + +# Secrets + +Use: + +```text +AI_BACKLOG_TOKEN +``` + +Environment variable only. + +Never store tokens in: + +- repository +- source code +- configuration files + +--- + +# Commands + +## Create Issue + +Command: + +```bash +ai-issue +``` + +Supported workflow: + +```text +Clipboard +↓ +Parse +↓ +Preview +↓ +Confirm +↓ +Create Issue +``` + +--- + +## Doctor + +Command: + +```bash +ai-issue doctor +``` + +Checks: + +- clipboard support +- git repository +- GitHub connectivity +- AI_BACKLOG_TOKEN availability + +Doctor command must not modify state. + +--- + +# Directory Structure + +Use: + +```text +cmd/ + ai-issue/ + +internal/ + clipboard/ + github/ + markdown/ + metadata/ + repository/ + publisher/ + +tests/ +``` + +Avoid: + +```text +pkg/ +services/ +helpers/ +utils/ +common/ +shared/ +``` + +Create packages around responsibilities. + +--- + +# Error Handling + +Return explicit errors. + +Do not silently continue. + +Examples: + +```text +Clipboard is empty. +``` + +```text +Current directory is not a git repository. +``` + +```text +Issue title could not be determined. +``` + +```text +AI_BACKLOG_TOKEN is not configured. +``` + +--- + +# Testing + +Use: + +```text +Go standard testing package +``` + +Do not introduce testing frameworks. + +Test: + +- markdown parsing +- repository resolution +- metadata generation +- issue payload generation + +Mock external systems when appropriate. + +Do not require GitHub access for unit tests. + +--- + +# Distribution + +Distribution method: + +```text +GitHub Releases +``` + +Artifacts: + +```text +macOS +Linux +Windows +``` + +Produce standalone binaries. + +Do not require runtime dependencies other than Git and GitHub access. + +--- + +# Non-Goals + +Do not implement: + +- AI APIs +- ChatGPT integration +- Claude integration +- Gemini integration +- pull request creation +- commit creation +- Slack integration +- Jira integration +- analytics +- project management features + +These are outside the scope of the project. + +--- + +# Framework Invariants + +The following conditions must always hold: + +```text +Author != Publisher +``` + +```text +GitHub Author == ai-backlog-bot +``` + +```text +Publisher == informational metadata only +``` + +```text +Single Binary CLI +``` + +Any implementation that violates these invariants is incorrect. +`````` diff --git a/src/content/frameworks/nextjs.mdx b/src/content/frameworks/nextjs.mdx new file mode 100644 index 0000000..dc4616c --- /dev/null +++ b/src/content/frameworks/nextjs.mdx @@ -0,0 +1,338 @@ +--- +title: 'NEXTJS.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 NEXTJS.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# NEXTJS.md + +## STACK + +REQUIRED + +- Next.js 16.x +- React 19.x +- JavaScript + +OPTIONAL + +- TailwindCSS 4.x +- TypeScript +- next-intl + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +FRAMEWORK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_ASSUME_NEXTJS_VERSION + +DO_NOT_GENERATE_DEPRECATED_PATTERNS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +app/ + +components/ +├── layout/ +├── sections/ +└── ui/ + +data/ +hooks/ +utils/ +styles/ +images/ + +public/ + +next.config.mjs +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_SRC_APP + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +routes -> app + +layout_components -> components/layout + +section_components -> components/sections + +reusable_ui_components -> components/ui + +static_content -> data + +navigation_data -> data + +custom_hooks -> hooks + +utility_functions -> utils + +global_styles -> styles + +project_images -> images + +public_assets -> public + +--- + +## ROUTING_RULES + +USE_APP_ROUTER_ONLY + +APP_ROUTER_IS_ROOT_LEVEL + +DO_NOT_USE_PAGES_ROUTER + +DO_NOT_CREATE_PAGES_DIRECTORY + +FOLLOW_NEXTJS_FILE_CONVENTIONS + +USE_ROUTE_GROUPS_WHEN_APPROPRIATE + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_CODE + +PRIVATE_FOLDERS_START_WITH_UNDERSCORE + +--- + +## COLOCATION_RULES + +ALLOW_ROUTE_LOCAL_COMPONENTS + +ALLOW_ROUTE_LOCAL_UTILITIES + +ALLOW_ROUTE_LOCAL_DATA + +USE_PRIVATE_FOLDERS_FOR_ROUTE_SPECIFIC_FILES + +PREFER_ROUTE_LOCAL_CODE_WHEN_NOT_SHARED + +USE_SHARED_DIRECTORIES_ONLY_FOR_REUSABLE_CODE + +--- + +## COMPONENT_RULES + +USE_SERVER_COMPONENTS_BY_DEFAULT + +ADD_USE_CLIENT_ONLY_WHEN_REQUIRED + +MINIMIZE_CLIENT_COMPONENTS + +PREFER_SERVER_RENDERING + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +--- + +## DATA_FETCHING_RULES + +FETCH_DATA_IN_SERVER_COMPONENTS_WHEN_POSSIBLE + +PREFER_ASYNC_SERVER_COMPONENTS + +AVOID_CLIENT_SIDE_FETCHING_UNLESS_REQUIRED + +DO_NOT_MOVE_SERVER_FETCHING_TO_CLIENT_COMPONENTS + +--- + +## API_RULES + +API_ROUTES_BELONG_IN_APP_API + +USE_ROUTE_HANDLERS + +FOLLOW_NEXTJS_API_CONVENTIONS + +DO_NOT_CREATE_CUSTOM_API_ARCHITECTURE + +--- + +## IMAGE_RULES + +USE_NEXT_IMAGE_WHEN_POSSIBLE + +PROJECT_IMAGES_BELONG_IN_IMAGES + +PUBLIC_ASSETS_BELONG_IN_PUBLIC + +OPTIMIZE_IMAGES + +--- + +## STYLING_RULES + +USE_PROJECT_DEFINED_STYLING_SOLUTION + +IF_TAILWIND_IS_INSTALLED + +USE_TAILWINDCSS_ONLY + +DO_NOT_MIX_MULTIPLE_STYLING_APPROACHES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## FORBIDDEN_DIRECTORIES + +- pages +- src +- features +- shared +- widgets +- modules +- views + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ALLOWED_ROOT_DIRECTORIES + +- app +- components +- data +- hooks +- utils +- styles +- images +- public + +ALLOWED_ROOT_FILES + +- package.json +- next.config.js +- next.config.mjs +- README.md +- jsconfig.json +- tsconfig.json + +DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_PATTERNS +4. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +DO_NOT_GUESS + +--- + +## NEXTJS_PRINCIPLES + +LATEST_STABLE_ONLY + +NEW_PROJECTS_ONLY + +APP_ROUTER_ONLY + +SERVER_FIRST + +SERVER_COMPONENTS_BY_DEFAULT + +MINIMIZE_USE_CLIENT + +MINIMIZE_CLIENT_SIDE_JAVASCRIPT + +RESPONSIVE_BY_DEFAULT + +ACCESSIBLE_BY_DEFAULT + +REUSE_BEFORE_CREATING +`````` diff --git a/src/content/frameworks/react-vite.mdx b/src/content/frameworks/react-vite.mdx new file mode 100644 index 0000000..a94dd39 --- /dev/null +++ b/src/content/frameworks/react-vite.mdx @@ -0,0 +1,343 @@ +--- +title: 'REACT_VITE.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 REACT_VITE.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# REACT_VITE.md + +## STACK + +REQUIRED + +- Vite 8.x +- React 19.x +- JavaScript +- TailwindCSS 4.x +- i18next 25.x +- react-i18next 15.x + +OPTIONAL + +- react-router-dom +- lucide-react +- axios +- zustand +- @tanstack/react-query +- react-hook-form +- zod + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED + +--- + +## VERSION_POLICY + +PACKAGE_JSON_IS_SOURCE_OF_TRUTH + +FRAMEWORK_MD_IS_FALLBACK + +USE_DECLARED_VERSIONS_ONLY + +DO_NOT_ASSUME_LIBRARY_VERSIONS + +DO_NOT_GENERATE_CODE_FOR_OTHER_VERSIONS + +WHEN_VERSION_CONFLICT_EXISTS + +FOLLOW_PACKAGE_JSON + +--- + +## PROJECT_STRUCTURE + +```text +src/ +├── assets/ +├── components/ +│ ├── layout/ +│ ├── sections/ +│ └── ui/ +├── pages/ +├── i18n/ +│ ├── locales/ +│ │ └── en.json +│ └── index.js +├── data/ +├── hooks/ +├── utils/ +├── App.jsx +├── main.jsx +└── index.css +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_NEW_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +FOLLOW_EXISTING_STRUCTURE_BEFORE_CREATING_NEW_STRUCTURE + +--- + +## FILE_PLACEMENT + +pages -> src/pages + +layout_components -> src/components/layout + +section_components -> src/components/sections + +reusable_ui_components -> src/components/ui + +page_specific_components -> src/pages/ + +static_content -> src/data + +navigation_data -> src/data + +faq_data -> src/data + +content_data -> src/data + +custom_hooks -> src/hooks + +utility_functions -> src/utils + +translation_files -> src/i18n/locales + +i18n_configuration -> src/i18n/index.js + +application_root -> src/App.jsx + +application_entry -> src/main.jsx + +global_styles -> src/index.css + +DO_NOT_CREATE_SUBDIRECTORIES_UNDER_PAGES + +DO_NOT_CREATE_COMPONENTS_OUTSIDE_DEFINED_LOCATIONS + +--- + +## ROOT_DIRECTORY_POLICY + +DO_NOT_CREATE_FILES_IN_REPOSITORY_ROOT + +UNLESS_EXPLICITLY_DEFINED_IN_ARCHITECTURE_MD + +PREFER_SRC_PLACEMENT_WHENEVER_POSSIBLE + +--- + +## FORBIDDEN_DIRECTORIES + +- features +- shared +- widgets +- modules +- stores +- state +- services +- api +- views + +DO_NOT_CREATE_FORBIDDEN_DIRECTORIES + +UNLESS_EXPLICITLY_DEFINED_IN_ARCHITECTURE_MD + +--- + +## NAMING_RULES + +COMPONENT_FILES -> PascalCase + +HOOK_FILES -> useCamelCase + +UTILITY_FILES -> camelCase + +DATA_FILES -> camelCase + +TRANSLATION_FILES -> language_code.json + +EXAMPLES + +- Header.jsx + +- HeroSection.jsx + +- PricingCard.jsx + +- useLanguage.js + +- useScrollPosition.js + +- navigationData.js + +- faqData.js + +DO_NOT_CREATE_INDEX_FILES_UNLESS_REQUIRED + +--- + +## COMPONENT_RULES + +USE_FUNCTION_COMPONENTS_ONLY + +DO_NOT_USE_CLASS_COMPONENTS + +ONE_COMPONENT_PER_FILE + +DO_NOT_EXPORT_MULTIPLE_COMPONENTS_FROM_SAME_FILE + +PREFER_SMALL_COMPOSABLE_COMPONENTS + +MOVE_REUSABLE_UI_TO_COMPONENTS_UI + +MOVE_PAGE_SPECIFIC_UI_TO_PAGE_DIRECTORY + +PREFER_COMPOSITION_OVER_COMPLEX_COMPONENTS + +--- + +## DATA_RULES + +STATIC_CONTENT_BELONGS_IN_SRC_DATA + +FAQ_CONTENT_BELONGS_IN_SRC_DATA + +NAVIGATION_CONTENT_BELONGS_IN_SRC_DATA + +CONTENT_BELONGS_IN_SRC_DATA + +DO_NOT_STORE_LARGE_CONTENT_BLOCKS_IN_COMPONENTS + +SEPARATE_CONTENT_FROM_PRESENTATION + +--- + +## STYLING_RULES + +USE_TAILWINDCSS_ONLY + +DO_NOT_USE_SCSS + +DO_NOT_USE_SASS + +DO_NOT_USE_CSS_MODULES + +DO_NOT_USE_STYLED_COMPONENTS + +DO_NOT_USE_EMOTION + +DO_NOT_USE_INLINE_STYLE_UNLESS_REQUIRED + +PREFER_TAILWIND_UTILITY_CLASSES + +--- + +## I18N_RULES + +SOURCE_LANGUAGE = ko + +KOREAN_IS_SOURCE_OF_TRUTH + +USE_KOREAN_TEXT_AS_TRANSLATION_KEYS + +ALL_USER_VISIBLE_TEXT_MUST_USE_TRANSLATION_FUNCTION + +DO_NOT_HARDCODE_USER_VISIBLE_TEXT + +DO_NOT_CREATE_KO_TRANSLATION_FILE + +ONLY_TRANSLATE_NON_SOURCE_LANGUAGES + +REQUIRED_FILES + +- src/i18n/locales/en.json + +EXAMPLE + +Component + +```jsx +__("회원가입"); +``` + +Translation + +```json +{ + "회원가입": "Sign Up" +} +``` + +WHEN_ADDING_NEW_TEXT + +1. USE_KOREAN_TEXT_AS_KEY +2. ADD_TRANSLATIONS_TO_ALL_NON_SOURCE_LANGUAGES +3. KEEP_TRANSLATIONS_SYNCHRONIZED + +FORBIDDEN + +```jsx +t("auth.register.button"); +``` + +```json +{ + "auth.register.button": "회원가입" +} +``` + +--- + +## ACCESSIBILITY_RULES + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT_FOR_IMAGES + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_VISIBLE_FOCUS_STATES + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_COMPONENTS +3. CHECK_EXISTING_DATA_FILES +4. CHECK_EXISTING_PATTERNS +5. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_NEW_FILES + +PREFER_EXISTING_PATTERNS_OVER_NEW_PATTERNS + +DO_NOT_INVENT_NEW_ARCHITECTURE + +DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY + +WHEN_UNCERTAIN_FOLLOW_EXISTING_CODEBASE + +ARCHITECTURE_MD_OVERRIDES_THIS_DOCUMENT + +TASKS_MD_OVERRIDES_ASSUMPTIONS + +PACKAGE_JSON_OVERRIDES_VERSION_ASSUMPTIONS + +DO_NOT_GUESS +`````` diff --git a/src/content/frameworks/vanilla.mdx b/src/content/frameworks/vanilla.mdx new file mode 100644 index 0000000..fa9c518 --- /dev/null +++ b/src/content/frameworks/vanilla.mdx @@ -0,0 +1,270 @@ +--- +title: 'VANILLA.md' +version: 'v1' +description: 'ReplWorks에서 제공하는 VANILLA.md framework 파일' +publishedAt: '2026-06-12T00:00:00Z' +--- + +``````markdown +# VANILLA.md + +## STACK + +REQUIRED + +- HTML5 +- CSS3 +- JavaScript ES2024 + +USE_DECLARED_STACK_ONLY + +DO_NOT_INTRODUCE_FRAMEWORKS + +DO_NOT_INTRODUCE_BUILD_TOOLS + +DO_NOT_INTRODUCE_PACKAGE_MANAGERS + +--- + +## PROJECT_STRUCTURE + +```text +/ +├── index.html +├── css/ +│ └── styles.css +├── js/ +│ └── main.js +├── images/ +└── assets/ +``` + +THIS_STRUCTURE_IS_AUTHORITATIVE + +DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES + +PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES + +--- + +## FILE_PLACEMENT + +html_pages -> repository_root + +stylesheets -> css + +javascript -> js + +images -> images + +static_assets -> assets + +DO_NOT_CREATE_SRC_DIRECTORY + +DO_NOT_CREATE_COMPONENT_DIRECTORIES + +DO_NOT_CREATE_BUILD_DIRECTORIES + +--- + +## HTML_RULES + +USE_SEMANTIC_HTML + +PREFER_NATIVE_HTML_ELEMENTS + +USE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT_FOR_IMAGES + +AVOID_UNNECESSARY_DIV_ELEMENTS + +--- + +## CSS_RULES + +USE_PLAIN_CSS + +STORE_GLOBAL_STYLES_IN_CSS_STYLES_CSS + +DO_NOT_USE_SCSS + +DO_NOT_USE_SASS + +DO_NOT_USE_LESS + +DO_NOT_USE_CSS_MODULES + +DO_NOT_USE_CSS_IN_JS + +DO_NOT_INTRODUCE_STYLING_FRAMEWORKS + +--- + +## JAVASCRIPT_RULES + +USE_VANILLA_JAVASCRIPT + +USE_ES_MODULES_WHEN_NEEDED + +PREFER_MODERN_BROWSER_APIS + +DO_NOT_USE_JQUERY + +DO_NOT_USE_REACT + +DO_NOT_USE_VUE + +DO_NOT_USE_ANGULAR + +DO_NOT_USE_SVELTE + +DO_NOT_USE_ALPINE + +DO_NOT_USE_HTMX + +--- + +## ASSET_RULES + +IMAGES_BELONG_IN_IMAGES + +FONTS_BELONG_IN_ASSETS + +ICONS_BELONG_IN_ASSETS + +DOWNLOADABLE_FILES_BELONG_IN_ASSETS + +DO_NOT_STORE_ASSETS_IN_CSS_OR_JS_DIRECTORIES + +--- + +## RESPONSIVE_RULES + +MOBILE_FIRST + +RESPONSIVENESS_IS_REQUIRED + +REQUIRE_RESPONSIVE_LAYOUTS + +REQUIRE_RESPONSIVE_TYPOGRAPHY + +REQUIRE_RESPONSIVE_IMAGES + +REQUIRE_FLEXIBLE_LAYOUTS + +AVOID_FIXED_WIDTH_LAYOUTS + +AVOID_HORIZONTAL_SCROLLING + +TEST_COMMON_VIEWPORT_SIZES + +RESPONSIVE_BEHAVIOR_OVERRIDES_DESKTOP_PREFERENCES + +--- + +## ACCESSIBILITY_RULES + +ACCESSIBILITY_IS_REQUIRED + +REQUIRE_PROPER_HEADING_HIERARCHY + +REQUIRE_ALT_TEXT + +REQUIRE_KEYBOARD_ACCESSIBILITY + +REQUIRE_SUFFICIENT_COLOR_CONTRAST + +ACCESSIBILITY_OVERRIDES_VISUAL_PREFERENCES + +--- + +## PERFORMANCE_RULES + +MINIMIZE_JAVASCRIPT + +MINIMIZE_DEPENDENCIES + +OPTIMIZE_IMAGES + +PREFER_NATIVE_BROWSER_FEATURES + +AVOID_UNNECESSARY_ABSTRACTIONS + +--- + +## FORBIDDEN_TOOLS + +- React +- Vue +- Angular +- Svelte +- Next.js +- Nuxt +- Astro +- Vite +- Webpack +- Parcel +- Rollup +- jQuery + +DO_NOT_INTRODUCE_FORBIDDEN_TOOLS + +UNLESS_EXPLICITLY_REQUESTED + +--- + +## ROOT_DIRECTORY_POLICY + +ROOT_HTML_FILES_ARE_ALLOWED + +DO_NOT_CREATE_CONFIGURATION_FILES + +DO_NOT_CREATE_PACKAGE_JSON + +DO_NOT_CREATE_NODE_MODULES + +DO_NOT_CREATE_BUILD_CONFIGURATIONS + +--- + +## GENERATION_POLICY + +BEFORE_CREATING_ANY_FILE + +1. CHECK_EXISTING_STRUCTURE +2. CHECK_EXISTING_PATTERNS +3. REUSE_BEFORE_CREATING + +PREFER_MODIFICATION_OVER_CREATION + +DO_NOT_INVENT_ARCHITECTURE + +DO_NOT_INTRODUCE_FRAMEWORKS + +WHEN_UNCERTAIN + +FOLLOW_EXISTING_CODEBASE + +--- + +## VANILLA_PRINCIPLES + +HTML_FIRST + +CSS_SECOND + +JAVASCRIPT_WHEN_NEEDED + +USE_NATIVE_BROWSER_FEATURES + +MOBILE_FIRST + +RESPONSIVE_BY_DEFAULT + +KEEP_IT_SIMPLE + +AVOID_DEPENDENCIES + +DO_NOT_INTRODUCE_FRAMEWORKS +`````` diff --git a/src/lib/site.ts b/src/lib/site.ts index fcea1ad..3a84c25 100644 --- a/src/lib/site.ts +++ b/src/lib/site.ts @@ -2,6 +2,7 @@ export const contentCollections = [ 'workflow', 'prompts', 'documents', + 'frameworks', 'tools', 'showcase', 'faq', @@ -23,6 +24,7 @@ export const collectionTitles: Record = { workflow: 'Workflow', prompts: 'Prompts', documents: 'Documents', + frameworks: 'Frameworks', tools: 'Tools', showcase: 'Showcase', faq: 'FAQ', From 6bfca273910cb1706efd75636ff02dce84f49936 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Fri, 12 Jun 2026 22:45:59 +0900 Subject: [PATCH 2/3] docs: review `/prompts/task-generation` content --- src/content/prompts/task-generation.mdx | 108 +++++++++++++++++++++--- 1 file changed, 98 insertions(+), 10 deletions(-) diff --git a/src/content/prompts/task-generation.mdx b/src/content/prompts/task-generation.mdx index 947c2be..d579a34 100644 --- a/src/content/prompts/task-generation.mdx +++ b/src/content/prompts/task-generation.mdx @@ -1,18 +1,106 @@ --- -title: 'Task Generation' +title: 'Task 생성' version: 'v1' -description: 'Prompt starter for generating task files from approved architecture.' +description: 'TASKS.md는 프로젝트의 현재 위치(Current Position)를 설명하는 문서다.' publishedAt: '2026-06-12T00:00:00Z' --- -```prompt -Generate TASKS.md from the approved product specification and architecture. +## 목적 -Requirements: -- one task per deliverable -- explicit execution order -- no future work -- no speculative scope +TASKS.md를 생성한다. -Output only the task list. +TASKS.md는 프로젝트의 현재 위치(Current Position)를 설명하는 문서다. + +--- + +## 산출물 + +```text +TASKS.md ``` + +--- + +## 사용 방법 + +ARCHITECTURE.md가 완성된 이후 사용한다. + +AI는 PRODUCT_SPEC.md와 ARCHITECTURE.md 요구사항을 지키는 TASKS를 체크리스트로 정리해야 한다. + +--- + +## Prompt + +``````prompt +# TASKS_PROMPT.md + +Generate TASKS.md. + +Assume PRODUCT_SPEC.md exists. + +Assume ARCHITECTURE.md exists. + +Assume FRAMEWORK.md exists. + +The purpose of TASKS.md is to define: + +```text +What remains to be implemented. +``` + +TASKS.md is an execution checklist. + +Do not describe architecture. + +Do not describe technologies. + +Do not describe frameworks. + +Do not describe implementation details. + +Do not reference specific classes. + +Do not reference specific files. + +Do not reference specific libraries. + +Generate implementation tasks only. + +Tasks should represent user-visible capabilities or architectural milestones. + +Each task must be independently completable. + +Each task must be independently testable. + +Organize tasks into phases. + +For each phase: + +- define tasks +- define acceptance criteria + +Tasks must: + +- be actionable +- be verifiable +- be implementation-independent + +Avoid: + +- implementation steps +- code-level instructions +- framework-specific instructions + +Include: + +- MVP +- Future + +Acceptance criteria must be objective. + +A task is complete only when acceptance criteria are satisfied. + +Optimize for autonomous execution by AI systems. + +The document is intended for AI implementation, not human project management. +`````` From e24ad1f411c9504cd0a9e309f0916a73c5779632 Mon Sep 17 00:00:00 2001 From: Samgu Lee Date: Fri, 12 Jun 2026 22:53:00 +0900 Subject: [PATCH 3/3] fix: broken links --- src/content/documents/agents.mdx | 2 +- src/content/documents/architecture.mdx | 2 +- src/content/documents/ideas.mdx | 2 +- src/content/documents/pitching-script.mdx | 2 +- src/content/documents/product-spec.mdx | 2 +- src/content/documents/tasks.mdx | 8 ++++---- 6 files changed, 9 insertions(+), 9 deletions(-) diff --git a/src/content/documents/agents.mdx b/src/content/documents/agents.mdx index 955e112..c2ef078 100644 --- a/src/content/documents/agents.mdx +++ b/src/content/documents/agents.mdx @@ -152,7 +152,7 @@ AGENTS.md는 ReplWorks 에서 표준 AGENTS.md를 제공한다. 실제 REPL Works Compatible 프로젝트 예시를 통해 AGENTS.md 작성 방식을 확인할 수 있다. -→ [Example AGENTS.md](./example-agents) +→ [Example AGENTS.md](/documents/example-agents) --- diff --git a/src/content/documents/architecture.mdx b/src/content/documents/architecture.mdx index c036a31..ffa3eed 100644 --- a/src/content/documents/architecture.mdx +++ b/src/content/documents/architecture.mdx @@ -146,7 +146,7 @@ Architecture Design Prompt는 다음을 수행한다. 실제 REPL Works Compatible 프로젝트 예시를 통해 ARCHITECTURE.md 작성 방식을 확인할 수 있다. -→ [Example ARCHITECTURE.md](./example-architecture) +→ [Example ARCHITECTURE.md](/documents/example-architecture) --- diff --git a/src/content/documents/ideas.mdx b/src/content/documents/ideas.mdx index 36b5bee..c6968c1 100644 --- a/src/content/documents/ideas.mdx +++ b/src/content/documents/ideas.mdx @@ -126,7 +126,7 @@ IDEAS.md는 일반적으로 다음 프롬프트를 통해 생성한다. 실제 REPL Works Compatible 프로젝트 예시를 통해 IDEAS.md 작성 방식을 확인할 수 있다. -→ [Example IDEAS.md](./example-ideas-md) +→ [Example IDEAS.md](/documents/example-ideas-md) --- diff --git a/src/content/documents/pitching-script.mdx b/src/content/documents/pitching-script.mdx index ed414f4..92cdfb0 100644 --- a/src/content/documents/pitching-script.mdx +++ b/src/content/documents/pitching-script.mdx @@ -123,7 +123,7 @@ PITCHING_SCRIPT.md는 일반적으로 다음 프롬프트를 통해 생성한다 실제 REPL Works Compatible 프로젝트 예시를 통해 PITCHING_SCRIPT.md 작성 방식을 확인할 수 있다. -→ [Example PITCHING_SCRIPT.md](./example-pitching-script) +→ [Example PITCHING_SCRIPT.md](/documents/example-pitching-script) --- diff --git a/src/content/documents/product-spec.mdx b/src/content/documents/product-spec.mdx index 111ec97..7525922 100644 --- a/src/content/documents/product-spec.mdx +++ b/src/content/documents/product-spec.mdx @@ -143,7 +143,7 @@ PRODUCT_SPEC.md는 일반적으로 다음 프롬프트를 통해 생성한다. 실제 REPL Works Compatible 프로젝트 예시를 통해 PRODUCT_SPEC.md 작성 방식을 확인할 수 있다. -→ [Example PRODUCT_SPEC.md](./example-product-spec) +→ [Example PRODUCT_SPEC.md](/documents/example-product-spec) --- diff --git a/src/content/documents/tasks.mdx b/src/content/documents/tasks.mdx index 1895c32..fe32bf6 100644 --- a/src/content/documents/tasks.mdx +++ b/src/content/documents/tasks.mdx @@ -33,9 +33,9 @@ TASKS.md는 프로젝트의 현재 상태를 설명한다. 일반적으로 다음 정보를 기반으로 작성한다. -- [PRODUCT_SPEC.md](./product-spec) -- [ARCHITECTURE.md](./architecture) -- [FRAMEWORK.md](./framework) +- [PRODUCT_SPEC.md](/documents/product-spec) +- [ARCHITECTURE.md](/documents/architecture) +- [FRAMEWORK.md](/documents/framework) - 현재 프로젝트 상태 - 승인된 요구사항 @@ -172,7 +172,7 @@ Task Generation Prompt는 다음을 수행한다. 실제 REPL Works Compatible 프로젝트 예시를 통해 TASKS.md 작성 방식을 확인할 수 있다. -→ [Example TASKS.md](./example-tasks) +→ [Example TASKS.md](/documents/example-tasks) ---