ai-study 작업 규칙

전역 = C:\dev\CLAUDE.md, 리포 = C:\dev\ai-study\CLAUDE.md. 여기엔 ai-study 인프라 함정만 쌓는다.

서버 4개 (전부 HKCU Run 자동시작 · 스크립트는 작업본 `C:\dev\ai-study\tools\`)

이름	포트	인터프리터	역할
`ai_study_site`	8801 (127.0.0.1)	py312w	운영 서빙 `prod\site` — `--prefix /study` 필수
`ai_study_test`	8803 (0.0.0.0)	py39w	테스트 서빙 작업본 `site` (312w는 방화벽 차단)
`ai_study_hook`	8802	py312w	GitHub webhook → prod git pull
`ai_study_qa`	8804	py312w	QA·과제 API

공개 = Tailscale Funnel /study→8801 · /study-qa→8804 · /study-hook→8802.
서버 스크립트는 작업본에서 돈다 → tools/*.py 수정은 재기동만으로 운영 반영(push 불필요). site/ 내용물만 push 대상.

🆕 신규

⛔26.9.9 폐기 — 서버 4개는 꺼졌고 자동시작도 지웠다. 위 표는 이제 「어떻게 돌았나」 기록이다. 후속 = projects/danggeun-ai-study/. 복원 절차(꼭 되살려야 할 때) = ①Run 키 백업 C:\dev\ai-study\data\study-share\hkcu_run_backup_20260909.reg 병합 후 로그온, 또는 그 안의 4줄을 직접 실행 ②tailscale funnel --https=443 --set-path /study http://127.0.0.1:8801 (+/study-qa→8804, /study-hook→8802). 🔴tailscale funnel reset 은 절대 쓰지 마라 — /·/agent·/furniture·/wmc/·/gdx/·/sci/·/bal/·/ain/ 까지 통째로 날아간다(경로별 --set-path <p> off 만 쓴다). 스크립트·site/·prod/·data/(계정·토큰·QA·제출물)는 하나도 안 지웠다.
도식 균등성은 「눈으로 맞추기」가 아니라 규격 고정으로 얻는다(26.9.9 세로판 개편). 원형판이 「화살표 길이·위치가 균등하지 않다」고 반려된 원인 = 라벨 길이로 pill 폭을 산출한 것 — 폭이 다르니 노드가 원주에서 차지하는 각도가 달라지고 그 사이 화살표 arc 가 제각각이 됐다. 처방 = 노드 규격·간격을 상수로 못박고(NW·NH·STEP) 자체검사에서 len(set(gaps)) == 1 을 강제(tools\build_promo_v.py). 라벨은 폭에 맞춰 줄이는 쪽이 맞다(검사도 글자수가 아니라 실폭 산출로: 한글 30 · 공백 12 · 중점 15). 부수 교훈 = 세로 흐름이 축소본 판독에서 원형보다 낫다(128px 에서 계단 형태가 남는다). 팔레트는 devplan 하우스 토큰이 단일 출처(#f6f3ee·#2b2622·#c97c4a·#8a5a3c·#f3e3d5) — Claude 코랄과 같은 계열이라 「클로드 컨셉」 요구도 이걸로 충족된다.
web-designer 에이전트는 처방만이 아니라 완성 파일 제작까지 시킬 수 있다(26.9.9 페페 지시). 「클로드 디자인에게 맡겨봐」 = 배경만 코디가 생성해 넘기고 HTML/CSS/SVG 제작·렌더·육안수정까지 위임. ⚠같은 폴더에 코디가 병행 제작하면 에이전트가 「다른 프로세스가 동시 작업 중」이라고 보고한다 → 파일명을 갈라야 한다(structure.html = 에이전트 / structure_v2.html = 코디). ⚠에이전트도 회전 텍스트 함정을 밟았다(rotate(-90) 세로 라벨 → 글자가 누워 안 읽힘, 2차 렌더에서 자가수정). ⛒참고 = DesignSync 도구는 claude.ai 디자인시스템 프로젝트 동기화용이라 홍보 이미지 1장에는 안 맞는다(컴포넌트 라이브러리 업로드 전용).
홍보용 도식 이미지 제작 함정 4개(26.9.9 당근 2차 구조도). 제작 = tools\build_promo.py(좌표계산→인라인 SVG+CSS HTML) → tools\render_promo.py(Playwright 2배 렌더 → LANCZOS 다운샘플 → JPG → 텔레그램 sendPhoto). ①🔴SVG marker-end 에 orient="auto-start-reverse" 를 쓰면 화살촉이 180° 뒤집힌다 — 그 값은 marker-start 전용이다. 순환도 화살표 6개가 전부 역방향으로 나왔고 렌더는 정상 종료해서 육안 전엔 안 잡혔다. orient="auto" 가 정답. ②한글은 word-break:keep-all 없으면 음절로 쪼개진다(「함/정 파일」·「모읍/니다」) — 카드형 도식에 기본으로 넣는다. ③pill 폭을 상수로 고정하면 라벨이 밖으로 넘친다 → 글자수 기반 산출(pill_w(): 한글 27 + 공백 10 + 아이콘 32 + 여백 46) + 인접 노드와 화살표 자리를 clear_deg() 로 각도 검산. ④포인트색 #c97c4a 위 페이퍼색 글자 = 2.94:1 로 큰글자 3:1 미달 → 순백이면 3.25:1 통과. 색 상수는 결정적이니 대비비 assert 를 빌드 자체검사에 박는 게 픽셀 스포이드보다 싸다. ⑤보조 = document.fonts.ready 대기 없이 캡처하면 폴백 폰트로 찍힌다(로컬 Noto Sans KR VF 사용). 배경만 나노바나나로 뽑고(imagegen.py) 글자·도형은 SVG/CSS — 한글을 이미지 생성에 맡기면 깨진다는 기존 규칙 그대로.
가입 = 토큰이 곧 초대장(26.8.22 페페 지시 · 팀장 승인 폐지). 토큰만 맞으면 status=approved + 즉시 sid. 함정 3개 = ①비번 6자 미만 계정은 자가가입 불가(서버 len(pw)<6·login.html minlength="6") → 짧은 비번을 지정받으면 규칙을 낮추지 말고 data/users.json에 계정을 직접 만든다(비번 규칙 완화는 site/ 변경 = push/운영배포까지 끌고 온다). 해시 = pbkdf2_hmac('sha256', pw, bytes.fromhex(salt), 200000), salt = secrets.token_hex(16). ②토큰 키(member 슬러그) 1계정 제한 — 같은 member로 두 번 가입하면 409. 그래서 미리 계정을 만들어 두면 그 토큰으론 더 못 가입한다. ③data/는 gitignore + 서버가 파일을 직접 읽음 → 토큰·계정 추가는 저장 즉시 반영(push 불필요), 단 NAMES 등 tools/*.py 수정은 qa_server 재기동이 있어야 먹는다.
Funnel은 마운트 프리픽스를 떼고 넘긴다 — 리다이렉트는 직접 복원해야 한다(26.8.11 장애). https://…/study/ 요청이 8801에 /로 도착한다. 8/3 로그인 게이트(5987736)의 미인증 302가 Location: /login.html을 그대로 내보내 funnel 루트(/→8788, 죽어 있음)로 튕겨 공개 사이트 전체가 502였다. 정적 에셋·login.html은 200이라 포트·프로세스 점검으로는 멀쩡해 보인다 — 죽은 건 서버가 아니라 리다이렉트 목적지다. → serve_site.py --prefix /study로 공개경로 복원, --selftest 5항목이 두 마운트 방식(프리픽스 붙은 채/뗀 채)을 함께 검증. 앞으로 8801에서 302를 만드는 코드를 건드리면 --selftest 먼저 돌린다.
git-bash에서 --prefix /study는 C:/Program Files/Git/study로 바꿔치기된다(MSYS 경로변환). → MSYS_NO_PATHCONV=1 prefix, 그리고 serve_site.py가 /로 시작 안 하면 즉시 종료(조용한 오설정 = 같은 장애 재발). HKCU Run은 Explorer가 띄우므로 무관.
"홈페이지 죽었다" 1차 점검 순서 = ①netstat -ano | grep ":880" 4포트 ②공개 URL을 curl -sL로 끝까지 추적(로컬 200이어도 공개 경로에서 나갈 수 있다) ③tailscale funnel status 매핑 ④프록시 대상 포트 개별 curl.
코디가 당근 모임에 직접 들어갔다 — 계정 「칼리」(26.9.9). 노트20 회선(010-2841-1731)으로 별도 계정을 만들어 「AI스터디 AI코딩 업무자동화」 모임(하안동·9/8 개설)에 가입 완료(멤버 6). 당근은 본인당 계정 3개까지 허용해 페페 기존 계정(010-9426-0731)과 공존한다 — 다만 1계정 1기기라 기존 계정으로는 절대 로그인하지 않는다(페페 폰이 튕긴다). 🔴가입 최대 함정 = 노트20이 KT 알뜰폰인데 adb 로는 판별이 안 된다(gsm.operator.alpha·ril.wfc.default_spn·carrierid 전부 KT 로 보인다) → 통신사를 「KT」로 고르면 「입력한 정보가 올바르지 않아요」만 반복하고, 「KT 알뜰폰」으로 바꾸면 즉시 통과. 약관 시트는 WebView(SignUpTermsWebActivity)라 체크박스 좌표가 안 먹고 라벨 노드 중심만 먹으며, 인증 실패 시 동의가 롤백돼 시트가 계속 다시 뜬다(= 체크 문제가 아니라 인증 실패 신호). 조작 = poin-agent\phone.py 재사용, 상세 = 코디 메모리 daangn-kali-account.