문서 갱신하기

PulseAd 소스 저장소에 새 커밋이 쌓이면 이 문서는 낡습니다. 갱신은 소스를 다시 읽고 소스가 실제로 바뀐 페이지만 다시 씁니다 — 나머지는 그대로 둡니다.

한 명령 방식

Claude Code에서 저장소 루트에서:

/sync-docs

이 명령이 아래 전체 절차를 실행하고, 먼저 diff 요약을 보여준 뒤 PR을 엽니다. 어떤 페이지의 소스도 바뀌지 않았으면 그렇다고 알리고 멈춥니다. 수동 단계는 거의 필요 없습니다 — /sync-docs가 무엇을 하는지 알 수 있도록 여기 적어둡니다.

단계별 동작

1. 최신 소스 가져오기

모든 소스 저장소를 .sources/(gitignore — 절대 커밋 안 함)로 클론/페치:

mkdir -p .sources
for r in ai-api pulsy-frontend pulsead-agents \
         snowflake-semantic-agent data_semanticview off-amazon-upload \
         aop-hermes banana-bunch ads-variation video-generator; do
  if [ -d ".sources/$r" ]; then git -C ".sources/$r" fetch --quiet origin;
  else gh repo clone "PulseAd/$r" ".sources/$r"; fi
done

(정규 저장소 + 브랜치 목록은 sync/manifest.json → sources.)

2. 고정 커밋 읽기

각 소스는 sync/manifest.json에 syncedCommit — 문서가 마지막으로 생성된 커밋 — 을 가집니다.

3. 각 저장소를 고정 커밋부터 라이브 HEAD까지 diff

모든 소스에 대해 고정 이후 바뀐 것을 나열하고 새 HEAD SHA를 기록:

git -C .sources/ai-api diff --name-only <syncedCommit>..origin/develop

4. 바뀐 파일 → 영향받은 페이지 매핑

매니페스트의 각 페이지는 "<source>:<path-prefix>" 형태의 derivedFrom 항목을 나열합니다. 바뀐 파일 경로가 그 prefix로 시작하면 해당 페이지가 영향받습니다. 어떤 페이지의 derivedFrom 아래 아무것도 안 바뀌었으면 그 페이지는 건드리지 않습니다.

5. 영향받은 페이지만 재생성 — 두 로케일 모두

AGENTS.md의 작성 규칙(모델부터; 낡은 내부 문서가 아니라 코드로 검증; 코드로 검증 가능한 함정만; placeholder만, 실제 브랜드 금지)을 따라 각 영향받은 페이지를 다시 씁니다. 영어 페이지와 /ko/의 한국어 미러를 둘 다 갱신. 코드가 답할 수 없는 것은 추측하지 않고 _internal/needs-johnny.md로 보냅니다.

6. 고정 커밋 갱신

각 건드린 소스의 syncedCommit을 라이브 HEAD SHA로, lastSyncedAt을 갱신하고, 재생성된 각 페이지의 status를 synced로 설정.

7. 검증

npm run build       # 사이트 빌드
npm run freshness   # 모든 페이지 출처 존재; 깨진 링크 없음

8. PR 열기

브랜치에 커밋하고 PR을 엽니다. main에 직접 푸시 금지.

언제 실행하나

• 소스 저장소에서 의미 있는 릴리스나 머지 후.
• 새 청중(파트너, 투자자)과 공유하기 전.
• 정기 주기(예: 주간)로 드리프트를 잡기 위해.

지금 얼마나 낡았는지는 sync/manifest.json의 lastSyncedAt과 각 sources.<name>.syncedCommit을 저장소 라이브 HEAD와 비교해 확인하세요.

자동화 (선택)

오늘 갱신은 온디맨드(사람이 /sync-docs를 트리거)입니다. 스케줄링할 수 있습니다 — 예: 3단계 diff를 돌려 페이지의 소스가 바뀐 경우에만 PR을 여는 작업 — 그러면 커밋이 들어올 때 자동으로 갱신됩니다. 아직 설정돼 있지 않으니, 원하시면 연결해 드리겠습니다.