docs: CLAUDE.md 에 세션 간 운영 암묵지 정리 #20

Merged

xhh merged 1 commit from docs/clarify-operational-knowledge into main

2026-04-22 02:24:33 +09:00

xhh commented

2026-04-22 02:24:32 +09:00

Owner

요약

세션 간 암묵지 정리. 다른 Claude 세션/압축된 세션이 시작 시 현 운영 상태를 한 번에 파악하도록 CLAUDE.md 에 7개 블록을 추가.

내용

Forgejo 연동: REST API 사용, Cloudflare WAF 의 UA 차단 대응, 토큰 위치/보안, Secrets·Variables·라벨·마일스톤 개요
NAS 배포 아키텍처: 경로 관례, 전용 Runner 필요 이유, host.docker.internal extra_hosts, Traefik/Cloudflare SSL 역할 분담
Docker 구성 특이사항: PYTHONPATH, HOME, chmod a+rX, uv.lock 커밋
Windows 로컬 환경: cp949 콘솔, 한글 바디 전달법, 파일 경로 관례
트랜잭션 관리: deps.get_session 의 commit/rollback/close 책임 (PR #17 잠복 버그 경고)
알려진 제약: RRPONTSYD fallback 정상화, tests/ 부재 -> Quality Foundation 마일스톤
history rewrite 전례: 개인 이메일 filter-repo 기록

## 요약 세션 간 암묵지 정리. 다른 Claude 세션/압축된 세션이 시작 시 현 운영 상태를 한 번에 파악하도록 CLAUDE.md 에 7개 블록을 추가. ## 내용 - **Forgejo 연동**: REST API 사용, Cloudflare WAF 의 UA 차단 대응, 토큰 위치/보안, Secrets·Variables·라벨·마일스톤 개요 - **NAS 배포 아키텍처**: 경로 관례, 전용 Runner 필요 이유, host.docker.internal extra_hosts, Traefik/Cloudflare SSL 역할 분담 - **Docker 구성 특이사항**: PYTHONPATH, HOME, chmod a+rX, uv.lock 커밋 - **Windows 로컬 환경**: cp949 콘솔, 한글 바디 전달법, 파일 경로 관례 - **트랜잭션 관리**: deps.get_session 의 commit/rollback/close 책임 (PR #17 잠복 버그 경고) - **알려진 제약**: RRPONTSYD fallback 정상화, tests/ 부재 -> Quality Foundation 마일스톤 - **history rewrite 전례**: 개인 이메일 filter-repo 기록

xhh added 1 commit

2026-04-22 02:24:32 +09:00

CLAUDE.md: 세션 간 암묵지 정리 — 다른 Claude 세션이 바로 이어갈 수 있도록 d71c663a4e

이번 세션에서 축적됐으나 문서 어느 곳에도 없던 운영 지식을 한 곳에 모아 새 세션/압축된 세션이 시작 시 현 상태를 빠르게 파악하도록 한다.

추가 섹션:

1. Forgejo 연동
   - REST API 직접 호출 (tea CLI 아님), Cloudflare WAF 가 Python urllib 기본 UA 를 1010/403 으로 차단하므로 User-Agent 필수
   - 액세스 토큰 위치(xvault 홈서버 로드맵), 로그 출력 금지
   - Secrets(FRED 계열) / Variables(API_URL) / 라벨·마일스톤 개요

2. NAS 배포 아키텍처
   - 경로 관례 /home/xhh/docker/<서비스>
   - 전용 Runner 가 필요한 이유(기본 Runner 이미지에 docker/curl/jq 없음)와 라벨 nas
   - host.docker.internal extra_hosts 로 Runner->Host API 도달
   - Traefik 은 HTTP 만, SSL 은 Cloudflare 종단

3. Docker 구성 특이사항
   - PYTHONPATH=/app/src (editable 설치 대체)
   - HOME 분리 (OpenBB 설정 경로)
   - chmod a+rX 런타임 복구 (v0.1.1 권한 깨짐 방어)
   - uv.lock 커밋 이유

4. Windows 로컬 환경
   - cp949 콘솔 -> logger.py UTF-8 reconfigure
   - 한글 바디는 UTF-8 파일로 전달
   - Edit/Write 는 역슬래시 경로

5. 트랜잭션 관리 (FastAPI)
   - api/deps.get_session 이 commit/rollback/close 책임 (PR #17 잠복 버그 경고)
   - 라우터는 flush+refresh 까지만

6. 알려진 제약
   - FRED RRPONTSYD fallback 정상화 완료
   - tests/ 자동 테스트 부재 — Quality Foundation 마일스톤(#18, #19) 에서 처리

7. 기존 "브랜치 & PR 흐름" 블록에 history rewrite 전례(개인 이메일 filter-repo) 각주 추가

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>