Mina Choi
6784e59ca5
git 저장소가 없어 히스토리·협업 기반이 아예 없던 상태를 연다.
함께 문서를 재편했다. 그동안 문서가 있어도 "이 제품이 뭘 푸는가"와
"어떻게 도는가"를 담은 문서가 없어서, 목표 문장이 backend/frontend
README 두 곳에 복붙돼 있었다 — 상위 문서가 없어 아래로 샌 것이다.
신설
README.md 레포 진입점 + 문서 지도 + 문서 규칙 4가지
AGENTS.md 에이전트·신규 합류자용 함정 목록과 규약
(CLAUDE.md 는 여기로 걸린 심볼릭 링크)
docs/PRODUCT.md 제품 정의 — 문제·사용자·원칙·**non-goals**·성공 기준
docs/ARCHITECTURE.md payload 경계·발행 파이프라인·서빙 결정·앱 분리 설계
이동
backend/docs/DECISIONS.md → docs/DECISIONS.md
백엔드만의 결정이 아니다. 게다가 코드 주석 ~25곳이 이미
`docs/DECISIONS.md` 로 적고 있어 레포 루트 기준으로는 그게 맞다.
갱신
docs/DEPLOY.md 서빙 결정 반영 — nginx 정적 서빙이 지금 경로(3절),
Azure 는 나중에 켤 때(4절)로 분리
docs/ARCHITECTURE.md 사이트 = 한 장(2026-08-31) 구조 반영
docs/COLLECTION_SEO_AEO_FLOW.md
robots.txt·sitemap.xml 은 오리진 루트에만 굽는다는 점 명시
frontend/site/scripts/prerender.ts
헤더 주석의 렌더 보고서 경로가 실제(422줄)와 달라 수정
.gitignore
★ CLAUDE.md 를 더 이상 무시하지 않는다. 에이전트 지침은 팀과 모든
에이전트가 공유하는 규약이라 커밋해야 한다 — 무시하면 클론한 사람이
"배포 후 republish_all.py 필수" 같은 함정을 전달받지 못한다.
개인용 오버라이드는 ~/.claude/CLAUDE.md 에 둔다.
5.1 KiB
5.1 KiB
AGENTS.md — 이 레포에서 작업하기 전에
에이전트와 신규 합류자가 먼저 읽는 파일이다. 여기에는 밟기 쉬운 함정과 규약만 둔다. 설명은 각 문서가 단일 출처다 — 여기로 복사하지 말고 링크한다.
| 궁금한 것 | 문서 |
|---|---|
| 이 제품이 뭘 푸나 · 안 하기로 한 것 | docs/PRODUCT.md |
| 어떻게 도나 · 앱 경계 | docs/ARCHITECTURE.md |
| 다음에 뭘 만드나 (우선순위 P0~P4) | docs/DEVELOPMENT_DIRECTION.md |
| 미결 사항 · 코드가 그걸 어떻게 격리했나 | docs/DECISIONS.md |
| 서버에 올릴 때 | docs/DEPLOY.md |
이 레포의 한 가지 규칙
백엔드는 HTML 을 만들지 않는다. payload JSON 을 파일로 떨어뜨리고, Node 프리렌더가 그걸 읽어 정적 사이트를 굽는다. 두 쪽은 서로를 모르고 디렉토리 하나로만 만난다. 이 경계를 넘는 변경은 하기 전에 ARCHITECTURE.md 1절을 읽는다.
반드시 알아야 할 함정
밟으면 조용히 틀린다 — 빌드는 성공하고 화면도 뜨는데 결과가 잘못된 종류다.
- 번들 파일명은 콘텐츠 해시다. HTML 은
/assets/index-DvNTmLhy.css를 루트 절대경로로 가리킨다. 경로는 프리렌더가dist/client/.vite/manifest.json에서 읽어 박는다 (prerender.ts:160). 렌더러 CSS 를 고치면 이름이 바뀐다. - 로컬
out/assets는 빌드마다 통째로 갈린다 (prerender.ts:573rmSync). 옛 해시 파일이 사라지므로 새 번들로 일부 사이트만 구우면 나머지는 CSS 가 404 다. → 프리렌더 기동 시 전체 재굽기가 이 구멍을 메운다. - ★ 프론트(
frontend/site)를 배포하면 반드시 전체 재굽기 + 전체 재업로드.azure_static.publish(slug)는 공용 자산 +s/<slug>만 올린다 — 렌더러를 고쳐도 다른 사이트에는 반영되지 않는다. →docker compose restart web후python scripts/republish_all.py - 발행 호스트는 두 곳에 있고 같아야 한다. 백엔드
SITE_PUBLIC_HOST(기본w4ai.o2o.kr,site_payload.py) ↔ 프론트VITE_PUBLISH_HOST. canonical·og:url·sitemap·IndexNow 가 전부 이 값을 쓴다. 그리고origin은 payload JSON 에 구워진다 — 호스트를 바꾸면 프리렌더 재실행만으로는 안 되고 백엔드에서 재발행해 payload 를 다시 만들어야 한다. AZURE_STORAGE_PREFIX와 루트 절대경로는 충돌한다. HTML 이/assets/…를 가리키는데 블롭은ai-for-web/assets/…에 놓인다. 접두사를 쓰려면 오리진 경로를/ai-for-web로 잡는 CDN 을 앞에 세워야 한다. 아니면 비워라. (프리렌더는 서브패스 마운트를 지원한다 —basePath가/sites/s/joy면 자산은/sites/assets.)AZURE_STORAGE_CONTAINER=$web— 셸에서 export 할 땐 반드시 작은따옴표('$web').- 슬러그 규칙은 두 곳에 있고 같아야 한다:
site_payload.publish_slug()↔frontend/shared/src/lib/slug.ts publishUrl. 어긋나면 발행은 성공하고 주소만 404 다. - 디렉토리 요청 →
index.html./s/<slug>가 끝 슬래시 없이 열려야 한다. 정적 서버를 바꾸든 nginx 설정을 만지든 이 규칙부터 확인한다.
코드 규약
- 미결 사항은 코드로 풀지 않는다. DECISIONS.md 1절이 보류한 것은 플래그·어댑터로 격리해 두고, 결론이 나면 날짜와 함께 결론을 적고 격리를 제거한다.
- 수집 어댑터를 추가하기 전에 DECISIONS.md 1-1 과 DATA_SOURCE_RESEARCH.md를 읽는다. 봇 탐지 우회는 결론과 무관하게 영구 금지다.
- 주석은 "왜"를 적는다. 이 레포의 기존 주석이 그 톤이다 — 실측값, 밟았던 함정, 안 한 이유. 코드를 읽으면 알 수 있는 "무엇"은 쓰지 않는다.
- 문서는 코드와 같은 커밋에서 고친다. 동작을 바꿨는데 문서를 안 고쳤으면 미완이다.
실행
docker compose up -d # API :9800 · 워커 · web :3000 · nginx :80
docker compose logs -f worker
- 발행 사이트:
http://localhost:3000/s/<slug>(admin Vite 가 :3001 정적서버로 프록시) - DB 는 compose 밖이다 (호스트 PostgreSQL,
host.docker.internal)..env없으면cp .env.example .env - 백엔드 스크립트는
backend/에서.venv/bin/python scripts/<name>.py - 테스트:
backend/에서.venv/bin/pytest.APP_ENV=test면.env를 읽지 않는다 — 실키가 테스트로 새어 외부 API 요금이 나가는 경로를 막아 뒀다
커밋
- 한 커밋 = 한 가지 변경. 문서와 그 문서가 설명하는 코드는 같은 커밋에 둔다.
- 커밋 메시지는 한국어로, 무엇을 왜 바꿨는지. 파일 목록은
git이 이미 안다.