diff --git a/src/content.config.ts b/src/content.config.ts index 2df6b40..0ba4291 100644 --- a/src/content.config.ts +++ b/src/content.config.ts @@ -1,4 +1,5 @@ import { defineCollection } from 'astro:content'; +import { glob } from 'astro/loaders'; import { z } from 'astro/zod'; const baseCollectionSchema = z.object({ @@ -10,18 +11,38 @@ const baseCollectionSchema = z.object({ export const collections = { manifesto: defineCollection({ + loader: glob({ + base: './src/content/manifesto', + pattern: '**/*.{md,mdx}', + }), schema: baseCollectionSchema, }), specification: defineCollection({ + loader: glob({ + base: './src/content/specification', + pattern: '**/*.{md,mdx}', + }), schema: baseCollectionSchema, }), workflow: defineCollection({ + loader: glob({ + base: './src/content/workflow', + pattern: '**/*.{md,mdx}', + }), schema: baseCollectionSchema, }), resources: defineCollection({ + loader: glob({ + base: './src/content/resources', + pattern: '**/*.{md,mdx}', + }), schema: baseCollectionSchema, }), showcase: defineCollection({ + loader: glob({ + base: './src/content/showcase', + pattern: '**/*.{md,mdx}', + }), schema: baseCollectionSchema, }), }; diff --git a/src/content/manifesto/v1.mdx b/src/content/manifesto/v1.mdx new file mode 100644 index 0000000..ebf587e --- /dev/null +++ b/src/content/manifesto/v1.mdx @@ -0,0 +1,103 @@ +--- +title: 'REPL Works 선언문' +version: 'v1' +type: 'manifesto' +description: 'REPL Works의 근본적인 신념과 원칙을 담은 선언문' +publishedAt: '2026-06-06T00:00:00Z' +--- + +## 서문 + +우리는 AI와 함께 제품을 만드는 더 나은 방법을 발견해 나가고 있다. + +AI 모델은 해마다 더 나은 코드를 생성한다. + +그러나 장기 프로젝트는 여전히 익숙한 이유들로 실패한다. + +프로젝트의 의도가 사라진다. + +아키텍처가 흔들린다. + +같은 실수가 반복된다. + +세션이 바뀔 때마다 맥락이 유실된다. + +모델을 교체하면 처음부터 다시 시작해야 하는 경우도 많다. + +우리는 이것이 AI의 지능이 부족해서 발생한다고 생각하지 않는다. + +우리는 프로젝트에 기억이 없기 때문에 발생한다고 믿는다. + +--- + +## 핵심 신념 + +AI의 기억은 일시적이다. + +프로젝트의 기억은 외부에 보존되어야 한다. + +모델은 잊는다. + +프로젝트는 잊어서는 안 된다. + +--- + +## 가치 + +우리는 모델 메모리보다 프로젝트 메모리를 중시한다. + +우리는 프롬프트 엔지니어링보다 아키텍처를 중시한다. + +우리는 긴 대화보다 지속 가능한 지식을 중시한다. + +우리는 에이전트의 지능보다 일관된 워크플로를 중시한다. + +우리는 특정 모델에 대한 의존보다 모델 독립성을 중시한다. + +우리는 빠른 구현보다 지속 가능한 개발을 중시한다. + +--- + +## 원칙 + +### 프로젝트 지식은 모델 밖에 존재해야 한다 + +프로젝트는 모델 업그레이드, 공급자 변경, 새로운 세션에도 살아남아야 한다. + +### 프로젝트의 기억은 지속되어야 한다 + +중요한 지식은 대화가 끝났다고 사라져서는 안 된다. + +### 아키텍처가 의도를 정의한다 + +구현은 아키텍처를 따라야 하며, 아키텍처를 대체해서는 안 된다. + +### 맥락은 한정된 자원이다 + +중요한 맥락은 반복적으로 재구성하는 것이 아니라 보존되어야 한다. + +### 모델은 교체 가능하다 + +프로젝트의 연속성은 특정 모델에 의존해서는 안 된다. + +### 장기적인 개발에는 장기적인 기억이 필요하다 + +프로젝트의 수명은 세션보다 길다. + +기억은 컨텍스트 윈도우보다 오래 지속되어야 한다. + +--- + +## 최종 선언 + +우리는 AI를 더 똑똑하게 만들려는 것이 아니다. + +우리는 프로젝트를 더 오래 지속 가능하게 만들고자 한다. + +AI 개발의 미래는 모델 내부의 더 나은 기억에 있지 않다. + +그것은 모델 외부의 더 나은 기억에 있다. + +모델은 잊는다.(Models forget) + +프로젝트는 잊어서는 안 된다.(Projects must not) diff --git a/src/content/resources/.gitkeep b/src/content/resources/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/content/showcase/.gitkeep b/src/content/showcase/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/content/specification/.gitkeep b/src/content/specification/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/content/specification/v1.mdx b/src/content/specification/v1.mdx new file mode 100644 index 0000000..9da3baf --- /dev/null +++ b/src/content/specification/v1.mdx @@ -0,0 +1,256 @@ +--- +title: 'REPL Works 스펙' +version: 'v1' +type: 'manifesto' +description: 'AI 시대에 프로젝트의 기억을 Git 기반 문서로 외부화하여 모델에 의존하지 않고 지속 가능하게 관리하는 Project Memory System.' +publishedAt: '2026-06-06T00:00:00Z' +--- + +# 목적 + +REPL Works는 AI 시대를 위한 **Project Memory System**이다. +이 문서는 REPL Works를 구성하는 최소 규칙을 정의한다. + +- Workflow는 구현체다. +- Specification은 표준이다. + +--- + +# 핵심 원칙 + +> AI의 기억은 일시적입니다. +> 프로젝트의 기억은 외부화되어야 합니다. + +--- + +> Models forget. +> Projects must not. + +--- + +# Rule 1. Git First + +모든 프로젝트는 Git Repository로 시작해야 한다. + +```bash +git init +``` + +프로젝트 기억은 Git에 저장된다. + +--- + +# Rule 2. Repository Is The Memory System + +프로젝트에 필요한 기억은 모델 내부가 아닌 Repository 내부에 존재해야 한다. + +프로젝트는 특정 모델에 의존해서는 안 된다. + +--- + +# Rule 3. AGENTS.md Is The Constitution + +모든 프로젝트는 `AGENTS.md`를 가져야 한다. +`AGENTS.md`는 프로젝트 헌법이다. + +--- + +### AGENTS.md는 최소한 다음 내용을 포함해야 한다 + +- 프로젝트 규칙 +- 개발 규칙 +- 테스트 규칙 +- 문서 위치 +- 논리적 Agent 정의 위치 + +--- + +모든 AI 작업은 `AGENTS.md`를 기준으로 수행된다. + +--- + +# Rule 4. Architecture Is Mandatory + +모든 프로젝트는 `ARCHITECTURE.md`를 가져야 한다. + +--- + +### ARCHITECTURE.md는 다음을 정의한다 + +- 시스템 구조 +- 폴더 구조 +- 데이터 흐름 +- 모듈 책임 +- 기술 스택 + +--- + +Architecture가 비대해질 경우 분리 가능하다. + +```text +architecture/ +├── frontend.md +├── backend.md +├── database.md +└── deployment.md +``` + +--- + +`ARCHITECTURE.md`는 진입점 역할을 수행한다. + +--- + +# Rule 5. Tasks Are Mandatory + +모든 프로젝트는 `TASKS.md`를 가져야 한다. + +--- + +`TASKS.md`는 TODO List다. + +--- + +Task는 반드시 Phase 단위로 관리한다. + +```text +Phase 1 + +[ ] Authentication +[ ] Database Setup + +Phase 2 + +[ ] Dashboard +``` + +--- + +- Architecture는 목적지다. +- Tasks는 현재 위치다. + +--- + +# Rule 6. Planning And Execution Must Be Separated + +계획 수립과 구현은 서로 다른 Runtime에서 수행한다. + +--- + +## Planning Runtime + +- IDEAS.md +- PITCHING_SCRIPT.md +- ARCHITECTURE.md +- TASKS.md + +--- + +## Execution Runtime + +- 구현 +- 테스트 +- 리팩토링 + +--- + +동일 컨텍스트에서 장기간 혼합하는 것을 권장하지 않는다. + +--- + +# Rule 7. Documentation Is AI Infrastructure + +`README.md`를 제외한 대부분 문서는 AI를 위한 문서다. + +--- + +- 문서는 설명서가 아니다. +- 문서는 프로젝트 기억 장치다. + +--- + +# Rule 8. Every Feature Requires Tests + +모든 기능은 테스트를 포함해야 한다. + +--- + +- 테스트 없는 구현은 완료된 구현으로 간주하지 않는다. +- Unit Test는 AI 환각을 줄이는 기본 안전장치다. + +--- + +# Rule 9. Architecture And Tasks Must Stay Consistent + +`TASKS.md` 변경이 Architecture에 영향을 준다면 +`ARCHITECTURE.md`도 함께 수정되어야 한다. + +--- + +- Architecture와 Tasks는 독립적으로 진화해서는 안 된다. + +--- + +# Rule 10. Models Are Replaceable + +REPL Works는 특정 모델에 의존하지 않는다. + +예: + +- GPT +- Claude +- Gemini +- Codex +- Cursor + +--- + +모델은 교체 가능해야 한다. +프로젝트 기억은 유지되어야 한다. + +--- + +# Rule 11. Session Memory Is Optional + +프로젝트 기억과 세션 기억은 다르다. + +--- + +## 프로젝트 기억 + +- Git +- AGENTS.md +- ARCHITECTURE.md +- TASKS.md + +--- + +## 세션 기억 + +- LONG_CONTEXT.md + +--- + +`LONG_CONTEXT.md`는 프로젝트 문서가 아니다. +세션 복구 문서다. + +--- + +- AI는 `LONG_CONTEXT.md`를 자동 참조해서는 안 된다. +- 사람이 필요할 때 수동으로 제공한다. + +--- + +# Compliance + +프로젝트가 **REPL Works Compatible**이려면 최소한 다음을 만족해야 한다. + +- Git Repository +- AGENTS.md +- ARCHITECTURE.md +- TASKS.md +- Test Coverage + +--- + +이 다섯 가지가 REPL Works의 최소 요구사항이다. diff --git a/src/content/workflow/.gitkeep b/src/content/workflow/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/src/content/workflow/v1.md b/src/content/workflow/v1.md new file mode 100644 index 0000000..6973f44 --- /dev/null +++ b/src/content/workflow/v1.md @@ -0,0 +1,632 @@ +--- +title: 'AI-Native Product Development Workflow' +version: 'v1' +type: 'workflow' +description: 'AI 시대에 프로젝트의 기억을 Git 기반 문서로 외부화하여 모델에 의존하지 않고 지속 가능하게 관리하는 Project Memory System.' +publishedAt: '2026-06-06T00:00:00Z' +--- + +# Philosophy + +AI 시대의 핵심 문제는 코드를 생성하는 능력이 아니다. + +핵심 문제는 다음과 같다. + +- 프로젝트 의도 유지 +- 아키텍처 일관성 유지 +- 작업 범위 제어 +- 반복 실수 방지 +- 컨텍스트 관리 +- 모델 교체 가능성 + +--- + +REPL Works는 AI Agent Framework가 아니다. + +REPL Works는 AI가 따라야 하는 Project Operating System이다. + +--- + +# Core Principles + +## AI Writes, Human Approves + +모든 문서는 AI가 작성한다. + +모든 코드는 AI가 작성한다. + +Human은 방향을 결정하고 결과를 검수한다. + +```text +AI +→ Write + +Human +→ Review +→ Approve +``` + +--- + +## Git Is The Source Of Truth + +프로젝트는 Git으로 시작한다. + +```bash +git init +``` + +모든 변경사항은 Git으로 관리한다. + +모든 구현은 Branch → PR → Merge를 통해 진행한다. + +--- + +## Models Are Replaceable + +```text +GPT +Claude +Gemini +Codex +Cursor +``` + +모두 교체 가능해야 한다. + +프로젝트의 가치는 모델이 아니라 Git에 저장된 지식에 있다. + +--- + +# Documentation Ownership + +## Planning Runtime + +채팅창 + +역할 + +```text +Document Creation +Document Revision +Architecture Design +Task Planning +Prompt Creation +Project Decisions +``` + +--- + +## Execution Runtime + +코딩창 + +역할 + +```text +Implementation +Refactoring +Testing +Bug Fixing +``` + +--- + +## Rule + +모든 Markdown 문서는 원칙적으로 Planning Runtime에서 생성한다. + +모든 Markdown 문서는 원칙적으로 Planning Runtime에서 수정한다. + +--- + +Execution Runtime은 문서의 대규모 수정(Rebuild, Rewrite, Revise)을 수행하지 않는다. + +--- + +예외적으로 다음 문서만 최소 수정 가능하다. + +```text +TASKS.md +ARCHITECTURE.md +``` + +--- + +# Workflow Overview + +```text +git init +↓ +IDEAS.md ++ +PITCHING_SCRIPT.md +↓ +commit +↓ +ARCHITECTURE.md +↓ +commit +↓ +PRODUCT_SPEC.md (Optional) +↓ +commit +↓ +AGENTS.md +↓ +commit +↓ +TASKS.md +↓ +commit +↓ +Development Loop +↓ +Release +↓ +README.md +``` + +--- + +# Phase 1. Idea Refinement + +## 목적 + +아이디어를 사업적으로 검증한다. + +--- + +AI와 반복적으로 토론한다. + +--- + +검토 항목 + +```text +아이디어가 충분히 매력적인가? + +2년 동안 유지 가능한가? + +예상 비용은 감당 가능한가? + +BEP는 언제 달성 가능한가? + +사용자 증가 예측은 합리적인가? +``` + +--- + +## 산출물 + +### IDEAS.md + +프로젝트 의사결정 문서 + +--- + +### PITCHING_SCRIPT.md + +프로젝트 의도 문서 + +--- + +## Commit + +두 문서는 반드시 같은 Commit으로 생성한다. + +```bash +git commit -m "docs: initialize product vision" +``` + +--- + +# Phase 2. Architecture Design + +## 목적 + +프로젝트 전체 구조 정의 + +--- + +실제 개발 단계에서 + +LLM은 ARCHITECTURE.md만 읽어도 프로젝트를 이해할 수 있어야 한다. + +--- + +IDEAS.md와 PITCHING_SCRIPT.md는 개발 단계의 필수 문서가 아니다. + +--- + +## Architecture Structure + +```text +ARCHITECTURE.md + +architecture/ +├── frontend.md +├── backend.md +├── database.md +└── auth.md +``` + +--- + +ARCHITECTURE.md는 Index 역할을 수행한다. + +--- + +세부 설계는 architecture 폴더에 위치한다. + +--- + +문서가 충분히 상세하다면 별도 SPEC 문서는 필요하지 않다. + +--- + +# Phase 3. Product Specification + +## Optional + +ARCHITECTURE.md가 충분하지 않을 경우에만 생성한다. + +--- + +포함 항목 + +```text +Node Version + +Python Version + +Go Version + +Database Version + +Package Manager Version + +OS Requirements +``` + +--- + +## 산출물 + +### PRODUCT_SPEC.md + +--- + +# Phase 4. Constitution + +## 목적 + +프로젝트 규칙 정의 + +--- + +## 산출물 + +### AGENTS.md + +--- + +AGENTS.md는 프로젝트 헌법이다. + +동시에 프로젝트 진입점이다. + +--- + +AI는 항상 AGENTS.md부터 읽는다. + +--- + +포함 항목 + +### Read Order + +```text +ARCHITECTURE.md + +PRODUCT_SPEC.md + +TASKS.md +``` + +--- + +### Agent Registry + +```text +agents/ +``` + +--- + +### Rules + +```text +Never create files in repository root + +Reuse existing components first + +Every feature must include unit tests + +Build must pass + +Lint must pass + +Tests must pass + +All task updates must trigger architecture review + +Only architecture-impacting changes may modify architecture documents +``` + +--- + +# Phase 5. Task Planning + +## 목적 + +현재 개발 상태 정의 + +--- + +## 산출물 + +### TASKS.md + +--- + +TASKS.md는 TODO List다. + +--- + +반드시 Phase로 그룹화한다. + +```text +Phase 1 + +- [ ] + +Phase 2 + +- [ ] +``` + +--- + +ARCHITECTURE.md는 목적지다. + +TASKS.md는 현재 위치다. + +--- + +# Development Loop + +## Step 1 + +TASKS.md에서 작업 선택 + +--- + +## Step 2 + +Planning Runtime에서 Prompt 생성 + +--- + +계획 수립과 구현은 분리한다. + +--- + +## Step 3 + +Branch 생성 + +```bash +git checkout -b feature/xxx +``` + +--- + +## Step 4 + +Execution Runtime에서 구현 + +--- + +모든 기능은 반드시 Unit Test를 포함해야 한다. + +--- + +필수 조건 + +```text +Build Success + +Lint Success + +Test Success +``` + +--- + +실패 시 수정 후 재실행한다. + +--- + +## Step 5 + +Pull Request 생성 + +--- + +## Step 6 + +Human Review + +--- + +## Step 7 + +Merge + +--- + +## Step 8 + +TASKS.md 업데이트 + +```text +- [x] +``` + +--- + +## Step 9 + +필요 시 ARCHITECTURE.md 업데이트 + +--- + +구조 변경이 발생한 경우에만 수행한다. + +--- + +# Long Context + +## 목적 + +LLM Session Memory 복구 + +--- + +LONG_CONTEXT.md는 프로젝트 문서가 아니다. + +--- + +LONG_CONTEXT.md는 세션 복구 문서다. + +--- + +다음 상황에서 사용한다. + +```text +새로운 모델 사용 + +새로운 채팅 시작 + +기존 채팅 Context 소멸 + +장기간 프로젝트 중단 후 재개 +``` + +--- + +사용 방법 + +새로운 채팅을 시작한 뒤 + +첫 메시지로 LONG_CONTEXT.md를 전달한다. + +--- + +LLM은 어떤 규칙으로도 LONG_CONTEXT.md를 자동 참조하지 않는다. + +--- + +AGENTS.md에 등록하지 않는다. + +--- + +## 생성 시점 + +소규모 프로젝트 + +```text +TASKS.md 완료 시 +``` + +생성 + +--- + +대규모 프로젝트 + +```text +Phase 완료 시 +``` + +생성 + +--- + +필요한 경우 수동으로 갱신할 수 있다. + +--- + +## 목적 + +대화 내용을 저장하는 것이 아니다. + +--- + +최근 프로젝트 문맥을 압축 보존하는 것이다. + +--- + +# Release + +배포 수행 + +--- + +# README.md + +유일한 Human-Oriented Document + +--- + +프로젝트가 충분히 완성된 이후 생성한다. + +--- + +# Persistent Assets + +프로젝트 기억 + +```text +Git + +ARCHITECTURE.md + +AGENTS.md + +TASKS.md +``` + +--- + +세션 기억 + +```text +LONG_CONTEXT.md +``` + +--- + +프로젝트 기억은 Git에 저장된다. + +세션 기억은 필요할 때 LLM에 주입된다. + +--- + +어떤 모델이든 + +프로젝트는 Git으로 복원할 수 있어야 한다. + +어떤 세션이든 + +LONG_CONTEXT.md로 이어갈 수 있어야 한다. diff --git a/src/pages/[collection]/[slug].astro b/src/pages/[collection]/[slug].astro index 5e21ac4..243f753 100644 --- a/src/pages/[collection]/[slug].astro +++ b/src/pages/[collection]/[slug].astro @@ -1,13 +1,26 @@ --- import type { ContentCollection } from '../../lib/site'; -import { collectionTitles, isContentCollection } from '../../lib/site'; -import { getEntry } from 'astro:content'; +import { + contentCollections, + collectionTitles, + isContentCollection, +} from '../../lib/site'; +import { getCollection, getEntry } from 'astro:content'; import DocumentLayout from '../../layouts/DocumentLayout.astro'; export async function getStaticPaths() { - return [] as Array<{ + const paths: Array<{ params: { collection: ContentCollection; slug: string }; - }>; + }> = []; + + for (const collection of contentCollections) { + const entries = await getCollection(collection); + paths.push( + ...entries.map((entry) => ({ params: { collection, slug: entry.id } })) + ); + } + + return paths; } const collection = Astro.params.collection; diff --git a/src/pages/[collection]/index.astro b/src/pages/[collection]/index.astro index cf8b645..f5b1847 100644 --- a/src/pages/[collection]/index.astro +++ b/src/pages/[collection]/index.astro @@ -5,6 +5,7 @@ import { contentCollections, isContentCollection, } from '../../lib/site'; +import { getCollection, render } from 'astro:content'; import DocumentLayout from '../../layouts/DocumentLayout.astro'; export async function getStaticPaths() { @@ -18,15 +19,35 @@ if (!isContentCollection(collection)) { const collectionTitle = collectionTitles[collection]; const collectionDescription = collectionDescriptions[collection]; + +const entries = await getCollection(collection); +const entry = entries[0] ?? null; +const rendered = entry?.rendered ?? null; +const contentResult = entry && !rendered ? await render(entry) : null; +const Content = contentResult?.Content ?? null; +const metadata = entry?.data ?? {}; --- - -
-

- No content has been added yet for {collectionTitle}. This collection route - is ready for future documents. -

-
+ + { + rendered ? ( +
+ ) : Content ? ( +
+ +
+ ) : ( +
+

+ No content has been added yet for {collectionTitle}. This collection + route is ready for future documents. +

+
+ ) + }