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 에 둔다.
78 lines
5.1 KiB
Markdown
78 lines
5.1 KiB
Markdown
# AGENTS.md — 이 레포에서 작업하기 전에
|
|
|
|
에이전트와 신규 합류자가 **먼저 읽는 파일**이다. 여기에는 *밟기 쉬운 함정*과 *규약*만 둔다.
|
|
설명은 각 문서가 단일 출처다 — 여기로 복사하지 말고 링크한다.
|
|
|
|
| 궁금한 것 | 문서 |
|
|
|---|---|
|
|
| 이 제품이 뭘 푸나 · **안 하기로 한 것** | [docs/PRODUCT.md](docs/PRODUCT.md) |
|
|
| 어떻게 도나 · 앱 경계 | [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) |
|
|
| **다음에 뭘 만드나** (우선순위 P0~P4) | [docs/DEVELOPMENT_DIRECTION.md](docs/DEVELOPMENT_DIRECTION.md) |
|
|
| 미결 사항 · 코드가 그걸 어떻게 격리했나 | [docs/DECISIONS.md](docs/DECISIONS.md) |
|
|
| 서버에 올릴 때 | [docs/DEPLOY.md](docs/DEPLOY.md) |
|
|
|
|
---
|
|
|
|
## 이 레포의 한 가지 규칙
|
|
|
|
**백엔드는 HTML 을 만들지 않는다.** payload JSON 을 파일로 떨어뜨리고, Node 프리렌더가 그걸 읽어
|
|
정적 사이트를 굽는다. 두 쪽은 서로를 모르고 **디렉토리 하나로만 만난다.**
|
|
이 경계를 넘는 변경은 하기 전에 [ARCHITECTURE.md 1절](docs/ARCHITECTURE.md)을 읽는다.
|
|
|
|
## 반드시 알아야 할 함정
|
|
|
|
밟으면 **조용히 틀린다** — 빌드는 성공하고 화면도 뜨는데 결과가 잘못된 종류다.
|
|
|
|
- **번들 파일명은 콘텐츠 해시다.** HTML 은 `/assets/index-DvNTmLhy.css` 를 **루트 절대경로**로
|
|
가리킨다. 경로는 프리렌더가 `dist/client/.vite/manifest.json` 에서 읽어 박는다
|
|
(`prerender.ts:160`). 렌더러 CSS 를 고치면 이름이 바뀐다.
|
|
- **로컬 `out/assets` 는 빌드마다 통째로 갈린다** (`prerender.ts:573` `rmSync`). 옛 해시 파일이
|
|
사라지므로 새 번들로 일부 사이트만 구우면 나머지는 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](docs/DECISIONS.md) 1절이 보류한 것은
|
|
플래그·어댑터로 격리해 두고, 결론이 나면 **날짜와 함께 결론을 적고 격리를 제거한다.**
|
|
- **수집 어댑터를 추가하기 전에** [DECISIONS.md](docs/DECISIONS.md) 1-1 과
|
|
[DATA_SOURCE_RESEARCH.md](docs/DATA_SOURCE_RESEARCH.md)를 읽는다.
|
|
봇 탐지 우회는 **결론과 무관하게 영구 금지**다.
|
|
- **주석은 "왜"를 적는다.** 이 레포의 기존 주석이 그 톤이다 — 실측값, 밟았던 함정, 안 한 이유.
|
|
코드를 읽으면 알 수 있는 "무엇"은 쓰지 않는다.
|
|
- 문서는 코드와 **같은 커밋**에서 고친다. 동작을 바꿨는데 문서를 안 고쳤으면 미완이다.
|
|
|
|
## 실행
|
|
|
|
```bash
|
|
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` 이 이미 안다.
|