REPL Works 웹사이트

1. 개요 (Overview)

REPL Works 웹사이트는 이 프레임워크의 공식 웹사이트이자, REPL Works 방법론과 문서를 실제로 적용한 첫 번째 도그푸딩 참조 프로덕트입니다.

소스는 GitHub에 공개되어 있고 MIT 라이선스입니다.

2. 사용된 표준 문서 (Documents Used)

.replworks/ 디렉터리에 표준 문서 6종을 유지하고, 저장소 루트의 AGENTS.md가 공통 규칙을 정합니다. 문서 전체는 저장소에서 볼 수 있습니다.

• 사람을 위한 문서: IDEAS.md, PITCHING_SCRIPT.md
• AI를 위한 문서: PRODUCT_SPEC.md, TECH_STACK.md, ARCHITECTURE.md, TASKS.md
• 공통 규칙: AGENTS.md (저장소 루트)

이 사이트는 문서를 소개하는 데 그치지 않고, 같은 저장소의 원본 파일을 그대로 보여줍니다. 표준 문서 페이지의 AGENTS.md와 프롬프트 페이지의 프롬프트는 templates/의 원본 파일을 빌드할 때 읽어 온 것이고, 복사한 사본이 아닙니다.

3. 적용 워크플로 (Workflow Usage)

웹사이트도 다음 순서로 개발합니다.

대화형 AI (제품 요구사항과 아키텍처 토론)
    ↓
REPL Works 문서 (Git 기반 마크다운으로 자산화)
    ↓
코딩형 AI (1-Prompt = 1-Task = 1-Commit으로 구현)
    ↓
Human Review (검증 결과를 확인하고 Merge)

이 흐름은 실제로 이렇게 돌았습니다. v2 출시 직전의 콘텐츠 리뷰가 대표적인 예입니다. TASKS.md의 T601부터 T606까지 여섯 개 태스크(워크플로, 프롬프트, 문서, 도구, 쇼케이스, FAQ 리뷰)를 각각 Issue 하나로 만들고(#38~#42, #48), Issue마다 PR 하나로 구현했습니다(#43~#47, #49). 태스크 6개, Issue 6개, PR 6개가 일대일로 대응합니다.

이 워크플로는 한 번 정해서 끝난 것이 아니라 사이트를 개발하면서 고쳐 왔습니다. 대표적인 변화는 다음과 같습니다.

• 규칙(AGENTS.md)은 이 저장소에서 먼저 바꿔 써 보고, 확정되면 사이트에 보이는 원본(templates/documents/AGENTS.md)에 반영합니다.
• 표준 문서와 프롬프트의 원본이 별도 저장소에 있던 것을 이 저장소의 templates/로 모았습니다. 이제 바뀌는 곳만 고치면 사이트가 따라옵니다.
• README에 있던 방법론 설명을 사이트로 일원화했습니다. 같은 내용이 두 곳에 있어서 갱신 순서가 서로 어긋났기 때문입니다. README는 개발과 운영에 필요한 내용만 남겼습니다.
• 두 AI 역할의 이름을 사이트 전체에서 대화형 AI와 코딩형 AI로 통일했습니다. 처음에는 Discussion AI와 Execution AI라고 불렀습니다.

4. 사용 기술 (Tools Used)

• Astro 7, Vite 8: 정적 사이트 컴파일 엔진
• Tailwind CSS 4, MDX, Expressive Code: 스타일, 콘텐츠 작성, 코드 블록 표시
• Pagefind: 서버 없이 동작하는 정적 검색
• Vitest, Playwright: 단위 테스트와 E2E 테스트
• ESLint, Prettier, astro check: 정적 검사
• astro-broken-links-checker: 빌드 중 깨진 내부 링크 검사
• GitHub Actions, GitHub Pages: 검증, 빌드, 배포
• ai-issue: GitHub Issue 자동화 CLI 도구

5. 배포와 운영 (Release & Operations)

배포는 GitHub Pages로 합니다. 서버가 없고, 사이트는 빌드 결과물이며 원본은 모두 Git에 있습니다.

배포. 이 사이트는 GitHub Release를 발행해야만 배포됩니다. 커밋을 올리거나 머지하는 것만으로는 배포되지 않고, 세상에 내보낼 시점은 사람이 정합니다. 그래서 릴리즈를 무겁게 만들지 않고 자주 발행합니다. 10월 3일 하루에만 v2.10.2부터 v2.11.2까지 릴리즈 11개를 발행했습니다. astro.yml은 Release를 발행하면 시작합니다. Actions에서 수동으로 실행할 수도 있는데, 이때는 배포할 릴리즈 태그를 직접 입력해야 하고 그 태그의 소스를 빌드해 배포합니다. 수동 배포도 태그가 있어야 합니다. Node 24로 npm ci를 실행하고, GitHub Pages 설정의 주소로 astro build를 실행해 dist/를 올립니다. 배포는 동시에 하나만 진행되고, 진행 중인 배포는 취소하지 않습니다.

검증. 검증은 두 곳에서 합니다. 먼저 변경을 올리기 전에 로컬에서 npm run check로 lint, 포맷, 타입, 테스트(Vitest와 Playwright), 빌드를 한 번에 확인합니다. 그다음 main이나 develop에 push하거나 PR을 올리면 GitHub Actions의 ci.yml이 lint, 포맷 검사, 빌드를 실행합니다. 빌드 단계에서는 깨진 내부 링크가 하나라도 있으면 실패하므로 로컬과 CI 양쪽에서 걸립니다. 테스트는 CI에서 돌리지 않고 로컬 npm run check에서만 돌립니다. src/site-invariants.test.ts는 사이트가 지켜야 할 불변 조건을 확인하는 테스트입니다. 예를 들어 AGENTS.md 문서 페이지가 templates/documents/AGENTS.md를 직접 참조하는지 검사합니다. 코드를 한 줄씩 읽어 검토하지 않고, 이 검사들을 통과하는지로 판단합니다.

검증과 배포의 관계. ci.yml은 push와 PR에서, astro.yml은 Release 발행이나 태그를 입력한 수동 실행에서 시작하는 별개의 workflow입니다. 그래서 CI가 실패해도 배포 workflow가 자동으로 막히지는 않고, Release를 발행하면 배포됩니다. astro.yml은 빌드만 하므로 테스트를 거치지 않습니다. CI 결과를 보고 Release를 발행할지는 사람이 정합니다. 자동 게이트로 막는 대신 Release를 발행하는 사람의 판단에 맡기는 것이 이 사이트의 운영 방식입니다.

상태와 복구. 서버나 데이터베이스가 없어서 백업할 상태가 없습니다. 소스는 Git에 있고, 사이트는 같은 소스에서 다시 빌드해 배포할 수 있습니다.

6. 학습된 레슨 (Lessons Learned)

Content First: 구현 코드는 언제든 바뀌지만, 잘 정제된 문서는 프로젝트의 기억으로 남습니다.

Discussion != Execution: 토론하는 AI와 구현하는 AI를 나누면 구현 단계는 확정된 문서가 정한 범위 안에서만 움직입니다.

Git Is Truth: 대화 세션은 사라지지만 Git 커밋과 마크다운 문서는 어떤 AI 모델이든 이어받을 수 있게 합니다.

Single Source of Truth: 원본은 한 곳에 둡니다. 같은 내용이 두 곳에 있으면 한쪽은 반드시 낡습니다. 방법론 설명이 README와 사이트에 따로 있을 때 갱신 순서가 서로 달랐고, 표준 문서와 프롬프트가 별도 저장소에 있을 때는 변경이 번거로웠습니다. 원본을 templates/에 모으고 사이트가 그것을 읽게 하자 바뀌는 곳만 고치면 되었습니다.