core2026/AGENTS.md

core2026 작업 지침

적용 범위와 목표

이 파일은 core2026/ 전체에 적용됩니다. 하위 디렉터리에 더 가까운 AGENTS.md가 생기면 사용자 지시, 가까운 파일, 이 파일, 상위 작업공간 지침 순으로 적용합니다.

목표는 ../ref/sam의 PHP 서비스를 TypeScript 런타임으로 호환 이관하는 것입니다. 내부 구조를 더 깔끔하게 만드는 일보다 기존 결과, 상태 전이, 권한, 화면과 운영 경계를 보존하는 일이 우선입니다.

현재 기준과 저장소 경계

• core2026/은 제품 구현 저장소입니다. gateway/game frontend·API, game engine, 공통 package, Prisma와 검증 도구가 실제로 존재합니다.
• PHP 기준 구현은 이 저장소 내부 legacy/가 아니라 ../ref/sam입니다. devel은 변경하지 않는 기준선이고 비교 fixture·계측은 ng_compare에만 두어 주세요.
• 아키텍처 매핑과 보고서는 별도 상위 저장소의 ../docs/ref-core2026-mapping.md, ../report/에 있습니다. 두 Git 경계의 commit과 상태를 혼동하지 말아 주세요.
• 이미지의 운영 소유자는 외부 Caddy의 /image/*입니다. 제품 저장소에 무단 복제하거나 앱 경로로 rewrite하지 말아 주세요.

작업 시작과 종료에 최소한 다음을 확인해 주세요.

git status --short --branch
git remote -v
git rev-parse HEAD

상위 매핑/보고서를 바꾸면 상위 저장소에서도 같은 검사를 별도로 수행해 주세요. dirty 파일은 사용자의 변경일 수 있으므로 관련 없는 수정, 정리, stage, commit 또는 삭제를 하지 말아 주세요.

완료 상태를 해석하는 법

2026-07-27의 백엔드 누락 감사에서는 현재 main에서 재현 가능한 구체적 미구현·미병합 항목을 찾지 못했습니다. 이를 “이관 전체 완료”로 해석하지 말아 주세요.

• 새 차등 fixture가 mismatch를 드러내면 다시 제품 결함으로 분류해 주세요.
• green unit test는 ref 호환, 실제 DB transaction, Chromium geometry 또는 운영 장애 복구를 자동으로 증명하지 않습니다.
• 환경 변수가 없는 기본 test에서 skip된 integration은 실행된 검증이 아닙니다.
• local/mock prefix E2E와 실제 외부 Caddy·host/firewall 검증은 별도입니다.
• report 제목의 완료보다 현재 코드, Git ancestry, 실행 경로와 재현 결과를 우선합니다.

기능 작업 전에 관련 매핑 항목과 최신 report를 읽고, 오래된 결론은 현재 코드와 commit으로 다시 확인해 주세요.

실제 구조와 책임

• app/gateway-frontend: 가입·로그인, 로비, 계정, 관리자 운영 UI
• app/gateway-api: 계정·세션·profile 정책, operation queue와 PM2 orchestration
• app/game-frontend: profile별 게임 SPA와 ref 호환 UI
• app/game-api: tRPC/SSE, 조회·입력 API와 battle/auction/tournament worker
• app/game-engine: turn daemon, scheduler, 월간 lifecycle와 DB flush
• packages/common: 타입, 직렬화, RNG와 공통 유틸리티
• packages/logic: 전투·명령·월간 action 등 도메인 로직
• packages/infra: gateway/game Prisma schema, migration과 client
• tools/integration-tests: PostgreSQL/Redis 및 ref↔core 차등
• tools/frontend-legacy-parity: 실제 Chromium 비교
• tools/legacy-db-migration: 장기보존 데이터 CLI 이관

tools/build-scripts/build-server.mjs는 현재 profile resource 복사 placeholder입니다. 이를 완성된 배포 bundle이나 검증된 profile build로 설명하지 않습니다. 운영 build/reset/open은 gateway operation, commit별 worktree와 orchestrator 실행 경로를 조사해 주세요.

레거시 매핑과 비교

기능을 변경하기 전에 다음을 end-to-end로 연결해 주세요.

1. ref entry point와 호출 순서
2. PHP domain class, SQL read/write, template/CSS/JS와 사용자 출력
3. core service/router/action/loader/flush와 frontend 호출부
4. session/auth, validation, transaction, 비동기 경계와 오류 복구
5. RNG 생성·소비와 persistence 순서

../docs/ref-core2026-mapping.md에는 1:1 대응을 억지로 만들지 말고 1:N/N:1 소유권과 변환 지점을 기록해 주세요. 확인, 부분 확인, 가설, 미구현, 의도적 차이를 근거와 함께 사용해 주세요. 문서와 코드가 다르면 먼저 양쪽 기준 commit과 실제 실행을 확인하고 사실관계를 고쳐 주세요.

ref 계측이 필요하면 다음을 지켜 주세요.

• devel에 test, endpoint, fixture나 debug 코드를 commit하지 말아 주세요.
• 기존 ng_compare 이력과 분기 기준을 조사하고 reset/overwrite하지 말아 주세요.
• 계측은 최소·deterministic·가능하면 read-only로 두고 test 환경 guard를 사용해 주세요.
• 계측 유무가 결과, RNG 소비, DB mutation과 출력 순서를 바꾸지 않는지 확인해 주세요.
• ref와 core 변경은 서로 다른 저장소와 commit으로 관리해 주세요.

호환성 우선순위

1. 전투 결과, 계산식, 판정·반올림·정렬과 RNG 소비 순서
2. 턴/명령 조건, 자원 변화, DB 상태 전이와 권한
3. API 요청·응답·오류, session과 인증
4. 문구, 로그, 화면 흐름과 룩앤필
5. 내부 구현 세부사항

레거시의 이상해 보이는 동작도 계약일 수 있습니다. 보안 또는 데이터 손상 위험이 아니면 우선 같은 동작을 재현하고 개선 제안은 분리해 주세요. 허용하는 차이는 사용자 경험, 저장 상태와 후속 턴 결과에 영향이 없다는 근거를 mapping/report에 남겨 주세요.

인증과 권한

• actor, general과 archive owner는 인증 session/token에서 서버가 결정합니다. client가 보낸 user ID, general ID, owner, role을 권한 근거로 신뢰하지 말아 주세요.
• game token의 profile, role, sanction과 장수 생성 정책을 world mutation보다 먼저 확인해 주세요.
• 새 browser flow는 x-session-token 또는 현재 session transport를 사용하고 token을 query string이나 로그에 노출하지 말아 주세요.
• 실패한 logout에서 client token을 먼저 버려 서버 revoke 실패를 숨기지 말아 주세요.
• 비밀번호 원문·OAuth credential·global salt·private key·session token을 Git, CLI argument, build log, report 또는 screenshot에 넣지 말아 주세요.
• VITE_*는 공개값입니다. 비밀값은 Git 제외 파일이나 /run/secrets/...를 사용해 주세요.

API를 변경하면 성공뿐 아니라 무인증, 다른 사용자, sanction/role, 잘못된 입력과 경계값을 검사해 주세요. 권한 테스트는 router mock만으로 끝내지 않고 위험도에 따라 실제 HTTP transport까지 확인해 주세요.

턴, transaction과 RNG

현재 gameplay mutation의 내구성 기준은 PostgreSQL input_event입니다.

API request
  -> input_event accept/idempotency
  -> daemon claim + lease/fencing 확인
  -> in-memory action/turn/monthly handlers
  -> world/log/queue/result flush
  -> input_event 완료를 같은 transaction으로 commit
  -> realtime 알림

• Redis pub/sub은 best-effort fan-out이며 mutation commit의 source of truth가 아닙니다.
• daemon lease/fencing을 우회하거나 이전 owner의 stale transaction을 commit 가능하게 만들지 말아 주세요.
• 예약 queue의 revision/CAS, repeat/bulk 직렬화와 API/daemon race를 보존해 주세요.
• 새 persistence field는 Prisma schema, 새 migration, domain/model type, loader, in-memory dirty state, transaction flush와 reload test까지 연결해 주세요.
• 기존 migration 파일이나 checksum을 수정하지 말아 주세요.
• 전투·명령·월간 action의 호출, state patch, 로그와 RNG 소비 순서를 리팩터링 편의로 바꾸지 말아 주세요.

게임 난수는 기존 packages/common/src/util/LiteHashDRBG.ts, RNG.ts, RandUtil.ts 흐름을 사용해 주세요. Math.random() 같은 임의 경로를 gameplay에 추가하지 말아 주세요. 후보가 하나뿐인 선택, 실패 분기, fallback에서도 ref가 소비하는 RNG call을 생략하지 말아 주세요.

전투/RNG 변경에는 fixed seed 결과뿐 아니라 RNG trace, 로그, 전체 state side effect와 실패 경로의 ref 비교가 필요합니다. comparator ignore를 늘리기 전에 canonical snapshot에서 누락된 field가 없는지 확인해 주세요.

프론트엔드와 룩앤필

새 디자인 시스템이나 현대적 재해석을 임의로 도입하지 말아 주세요. 보존 범위는 layout, font, line-height, 줄바꿈, 색상, texture, border, shadow, opacity, 이미지 natural size/aspect ratio/object-fit과 표시 순서입니다.

• gateway /gateway/, game /che/와 /hwe/ prefix에서 direct navigation, refresh, tRPC, SSE와 asset URL을 확인해 주세요.
• kwe, twe, nya, pya, pwe가 코드에 있어도 외부 route가 활성화된 것으로 가정하지 말아 주세요.
• /image/*를 frontend build artifact로 가져오거나 root 배포 URL로 하드코딩하지 말아 주세요.
• 공통화는 동일한 렌더링 계약이 확인된 token/shell에 한합니다. .error, .stack처럼 이름만 같은 page selector를 전역화하지 말아 주세요.
• v-html은 입력 source와 sanitization/allowlist를 확인해 주세요. 기존 warning을 일괄 disable하지 말아 주세요.

UI를 변경하면 실제 Chromium을 사용해 주세요.

• ref와 core에 같은 Chromium, viewport, device scale, zoom, locale, font, image와 로그인/test data를 사용해 주세요.
• 전체·영역 screenshot과 getBoundingClientRect(), getComputedStyle()을 수집해 주세요.
• hover(), focus, pointer down/up, checked/selected/disabled, dropdown, modal과 transition 상태를 실제 interaction으로 만들어 주세요.
• pixel diff mask는 시간·난수 등 불가피한 영역만 최소화하고 이유를 기록해 주세요.
• auth redirect만 확인하고 visual parity라고 주장하지 말아 주세요.
• 민감정보가 보이는 artifact는 저장하거나 report에 넣지 말아 주세요.

CSS layer와 selector 경계는 docs/frontend-css-architecture.md, 비교 실행은 docs/frontend-legacy-parity.md를 따라 주세요.

DB와 레거시 데이터 이관

Gateway는 기본 public, game은 profile별 PostgreSQL schema를 사용합니다. schema 변경 후 최소한 다음을 위험도에 맞게 확인해 주세요.

• 빈 DB migration 전체 적용
• 두 번째 deploy가 no-op인지
• 기존 설치에서 증분 적용되는지
• unique/FK/index와 runtime query 일치
• rollback 또는 backup/restore 경로

prisma db push는 격리된 fixture에서 scoped schema 확인용으로만 사용하고 정식 migration chain을 대신하지 말아 주세요.

레거시 DB 이관은 tools/legacy-db-migration CLI만 사용해 주세요.

• dry-run이 기본이며 실제 쓰기는 명시적 --apply가 필요합니다.
• DB URL과 secret은 환경/secret file로 전달해 주세요.
• PostgreSQL advisory lock, stable legacy key와 idempotent upsert를 보존해 주세요.
• 현 시즌 general/city/nation, queue, message, market, log와 seasonal storage를 장기보존 이관에 섞지 말아 주세요.
• 운영 apply 전 backup, maintenance mode, source/target count와 rollback 절차를 다시 확인해 주세요.
• dump에 우연히 있는 table이 아니라 ref schema와 사용자 범위를 기준으로 삼아 주세요.

환경과 배포

.env 또는 secret key를 추가하기 전에 .gitignore와 .env.example을 함께 갱신해 주세요. example은 모든 필수 key와 명백한 placeholder를 포함하되 실제 비밀을 담지 말아 주세요.

전체 작업공간의 개발 PostgreSQL/Redis는 ../docker_compose_files/development/에서 worktree별로 격리할 수 있습니다. 통합 fixture는 schema truncate와 Redis 초기화를 수행할 수 있으므로 병렬 worktree가 같은 instance를 공유하지 않도록 해 주세요. volume 삭제 명령은 사용자가 명시적으로 데이터 폐기를 요청하지 않으면 실행하지 말아 주세요.

현재 외부 호스트 계약은 0.0.0.0 bind와 /gateway/, /che/, /hwe/ prefix입니다. Caddy는 외부 인프라로 취급하고 요청 없이 설정 변경을 전제하지 않습니다. local preview/mock 성공을 외부 HTTPS 성공으로 보고하지 말아 주세요.

Gateway preview를 검증할 때 최소 계약은 다음과 같습니다.

VITE_APP_BASE_PATH=/gateway \
VITE_GATEWAY_API_URL=/gateway/api/trpc \
VITE_GAME_API_URL_TEMPLATE='/{profile}/api/trpc' \
VITE_GAME_WEB_URL_TEMPLATE='/{profile}/' \
pnpm --filter @sammo-ts/gateway-frontend build

profile별 정확한 포트와 game frontend/API 변수는 docs/e2e-caddy-routing.md에서 확인하고 현재 인프라와 대조해 주세요.

개발과 검증 절차

1. 현재 branch/status/remote, 사용자 변경과 가까운 지침을 확인해 주세요.
2. 관련 mapping/report와 ref/core 호출 경로를 조사해 주세요.
3. 보존할 계약, 허용할 차이와 검증 범위를 먼저 정합니다.
4. 코드와 함께 type/schema/migration/fixture/mapping을 갱신해 주세요.
5. 좁은 단위 test → typecheck/lint/build → DB integration → ref 차등 → Chromium E2E 순으로 위험에 맞게 넓혀 주세요.
6. 명령, 결과, skip/미검증과 baseline failure를 분리해 report에 기록해 주세요.
7. 양쪽 Git diff/status와 필요한 ancestry를 다시 확인해 주세요.

기본 정적 검사는 실제 루트 script를 사용해 주세요.

CI=1 pnpm typecheck
pnpm lint
pnpm test
pnpm build

• 모든 코드 변경 후 CI=1 pnpm typecheck를 실행해 주세요.
• pnpm test의 skip 수를 pass처럼 보고하지 말아 주세요.
• Vitest file/name filter는 package script 뒤에 불필요한 --를 넣지 말아 주세요. 예: pnpm --filter @sammo-ts/game-engine test monthlyCoreEventHandler.test.ts
• frontend package의 test placeholder를 실제 UI 검증으로 오해하지 말아 주세요. 해당 Playwright script 또는 legacy parity suite를 사용해 주세요.
• 전체 lint/test의 기존 실패가 있으면 targeted 결과와 baseline 재현 결과를 구분하고, 관련 없는 기대값을 완화해 숨기지 말아 주세요.

외부 서비스 없는 기본 integration:

pnpm test:integration

전용 PostgreSQL/Redis를 준비한 조건부 전체 경계:

pnpm test:integration:conditional

ref 명령과 UI entry point:

pnpm check:legacy:general
pnpm check:legacy:nation
pnpm test:e2e:frontend-legacy

각 command가 요구하는 ref checkout, Docker, DB URL, secret과 fixture는 관련 docs에서 확인해 주세요. 존재하지 않는 명령을 오래된 report나 제안 문서만 보고 실행하지 말아 주세요.

코드 스타일

• TypeScript는 workspace 전체에서 정확히 6.0.2를 사용해 주세요. package-local 다른 버전을 추가하지 말아 주세요.
• TypeScript/JSON/Vue SFC는 기존 4-space 스타일을 유지해 주세요.
• public API는 명시적 타입을 사용하고 any, 불필요하게 넓은 unknown, as unknown as 우회를 피해 주세요.
• Vue component는 PascalCase, composable은 useX, 변수/함수는 camelCase, type/class는 PascalCase를 사용해 주세요.
• 한국어 domain identifier와 설명은 의미가 더 명확할 때 유지해 주세요.
• action/command/전투 코드에는 한국 독자가 side effect와 ref 근거를 이해할 수 있는 주석을 남기되 코드의 반복 설명은 피해 주세요.
• 기능 이관과 무관한 대규모 formatting/refactor를 같은 변경에 섞지 말아 주세요.

문서와 보고서

기능·운영·호환성에 의미 있는 변경은 코드와 같은 작업에서 다음을 갱신해 주세요.

• README.md: 사용자가 알아야 할 현재 구조, 시작점과 운영 경계
• 이 AGENTS.md: 반복 작업 규칙과 검증 계약
• docs/*: core2026 내부 구현·운영 상세
• ../docs/ref-core2026-mapping.md: ref↔core 근거와 상태
• ../report/YYYY-MM-DD-간결한-작업명.md: 재현 가능한 인수인계

보고서에는 목적/범위, 조사한 ref, 변경 파일, 보존 계약, 명령과 결과, skip/미검증, 알려진 차이, 후속 작업과 저장소별 commit을 포함합니다. commit 전이면 커밋 전으로 기록하고 서로 다른 저장소의 hash를 명확히 구분해 주세요.

Git, worktree와 commit

• 중·장기 작업은 전용 branch/worktree와 고유 DB/Redis instance에서 합니다.
• 최신 main을 통합하고 회귀를 확인한 뒤 요청된 범위에 따라 local main에 병합해 주세요. 원격 push는 별도 요청 없이는 하지 말아 주세요.
• 관련 없는 사용자 변경을 stage/commit/revert하지 말아 주세요.
• ref 비교 변경과 core 제품 변경, 상위 mapping/report 변경은 각 Git 저장소에서 별도 commit해 주세요.
• 생성물, .env, DB volume, log, coverage, screenshot, test-results와 secret을 commit하지 말아 주세요.
• worktree 정리는 clean status와 git merge-base --is-ancestor HEAD <baseline>을 모두 확인한 뒤 non-force 제거해 주세요. 이름, 나이 또는 uncommitted 여부만으로 삭제하지 말아 주세요.
• 사용자가 commit을 요청하지 않은 일반 작업은 diff와 권장 commit 경계를 준비하되 임의로 commit하지 말아 주세요.

Qwen 보조 분석

Qwen은 대규모 파일 목록, diff·로그 분류, 반복 추출과 누락 후보 재검색에만 사용해 주세요. 필요한 최소 발췌만 전달하고 secret, 개인정보와 환경 파일 값을 보내지 말아 주세요.

• 아키텍처·보안·DB mutation·전투/RNG 판단과 최종 검증을 위임하지 말아 주세요.
• 결과는 파일, Git, test 또는 실제 trace로 독립 검증해 주세요.
• 응답 budget은 128–4096 token 범위로 제한해 주세요.
• 실패하면 health 확인 후 일시 오류일 때 한 번만 재시도하고, 선택적 작업이면 로컬 분석을 계속해 주세요.