From cb312f02b31abb76df55ed2c4123e11ae0c71d93 Mon Sep 17 00:00:00 2001 From: Hide_D Date: Mon, 5 Jan 2026 15:45:22 +0000 Subject: [PATCH] =?UTF-8?q?docs:=20AGENTS.md=20=EB=AC=B8=EC=84=9C=EC=97=90?= =?UTF-8?q?=20=EC=84=B9=EC=85=98=20=EC=B6=94=EA=B0=80=20=EB=B0=8F=20?= =?UTF-8?q?=EB=82=B4=EC=9A=A9=20=EC=A0=95=EB=A6=AC?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 26 ++++++++++++++++++++++---- 1 file changed, 22 insertions(+), 4 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 6da623d..ebb51ca 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,18 +1,21 @@ # Repository Guidelines ## Project Goal (Rewrite) + - This repository is transitioning from the legacy PHP codebase to a TypeScript-based monorepo using pnpm workspaces. - The legacy game remains the current active source under `legacy/` while the rewrite is prepared alongside it. - Legacy data under `legacy/` is for migration only; once DB migration is complete, the runtime will no longer depend on legacy data. ## Project Naming + - Official name: 삼국지 모의전투 HiDCHe - Common nicknames: 삼모, 삼모전, 힏체섭 - Short forms in code/docs: sammo, hidche - TypeScript rewrite working name: sammo-ts ## Project Structure & Module Organization + - `legacy/` contains the application source. This is the active codebase. - PHP entry points live under `legacy/` and `legacy/hwe/` (for example `legacy/index.php`, `legacy/hwe/index.php`). - `legacy/` is mostly a shell; `legacy/src/` is largely unused. @@ -23,12 +26,14 @@ - Static data/assets: scenarios in `legacy/hwe/scenario/`, templates in `legacy/hwe/templates/`. ## Legacy Endpoint Patterns + - JSON API handlers: `legacy/hwe/j_*.php`. - Vue multi-entry pages: `legacy/hwe/v_*.php`. - Legacy PHP + jQuery pages: `legacy/hwe/b_*.php` with POST handlers in `legacy/hwe/c_*.php`. - Modern API router: `legacy/hwe/api.php` accepts a path argument and dispatches to `legacy/hwe/API/` modules. ## Planned Monorepo Layout (TypeScript Rewrite) + - `/packages/common`: shared utilities and type definitions. - `/packages/infra`: Prisma/Redis connectors and other runtime infra. - `/packages/logic`: pure game logic with DI/interfaces for external dependencies. @@ -40,6 +45,7 @@ - `/tools/build-scripts`: build and deployment scripts. ## Planned Runtime & Tooling + - Backend: Node.js + Fastify, with Prisma ORM. - Turn daemon: turn scheduler/resolver service for game ticks. - Turn daemon and API server communicate via Redis Stream or Redis pub/sub. @@ -52,21 +58,26 @@ - Build output: server builds emitted to `/dist/{profileName}` per profile. ## Suggested Monorepo Scripts (Proposal) + These are placeholders to align teams; adjust once packages exist. + - `pnpm install`: install all workspace dependencies. -- `pnpm -r lint`: lint all packages. -- `pnpm -r test`: run all unit tests (Vitest where configured). -- `pnpm -r build`: build all packages/apps. -- `pnpm -r dev`: run dev servers where applicable. +- `pnpm typecheck`: run TypeScript type checks in all packages. +- `pnpm lint`: lint all packages. +- `pnpm test`: run all unit tests (Vitest where configured). +- `pnpm build`: build all packages/apps. +- `pnpm dev`: run dev servers where applicable. - `pnpm --filter ./app/game-frontend dev`: run a single app by filter. - `pnpm --filter ./app/game-api dev`: run a single service by filter. - `pnpm --filter ./app/game-engine dev`: run a single service by filter. ## Development Checklist (AI) + - After code changes, verify TypeScript type checks (prefer `pnpm -r build` or the package `tsc`). - When changes require unit tests, run the relevant tests. ## Build Profiles (Proposal) + - A build profile is a server+scenario pair; scenario selection is required even if a default exists. - Server builds should accept a profile (server variant) plus an explicit scenario file input. - Recommended pattern: a `tools/build-scripts` runner invoked by pnpm, e.g. `pnpm build:server --profile che --scenario default`. @@ -76,10 +87,12 @@ These are placeholders to align teams; adjust once packages exist. - The scenario file determines unit sets and DB settings that must be prepared before build output is emitted. ## Server Profiles (Planned) + - Server IDs: `che`, `kwe`, `pwe`, `twe`, `nya`, `pya` - Each build/run profile combines a server ID with a scenario selection. ## Game Domain Notes (Behavioral Context) + - Turn-based multiplayer loop with configurable tick length (historically 120/60/30/20/10/5/2/1 min; experimental day/night schedules). - Core stats: leadership, strength, intelligence with effects on internal affairs and combat. - Traits and modifiers apply via the Trigger system, evaluated by priority; "attempt" then "execute". @@ -87,12 +100,14 @@ These are placeholders to align teams; adjust once packages exist. - "Unit packs" bundle unit graphics, audio, and special effects per scenario. ## Randomness Policy (Verifiable RNG) + - All game-impacting randomness must be verifiable and reproducible from a deterministic seed. - Prefer reusing the existing TypeScript implementations: `legacy/hwe/ts/util/LiteHashDRBG.ts` and `legacy/hwe/ts/util/RNG.ts` with minimal or no changes. - Seed composition should include a hidden base seed plus action context (action type, time, actor, target) so results can be re-validated later. - Do not introduce ad-hoc randomness in game logic; allow non-deterministic randomness only for non-gameplay, cosmetic, or UI-only cases. ## Coding Style & Naming Conventions + - Follow repo lint/format configuration once it exists; keep diffs consistent within a file. - Indentation: 4 spaces for TypeScript, JSON, and Vue SFCs. - Prefer explicit types for public APIs; avoid `any` and narrow `unknown`. @@ -103,15 +118,18 @@ These are placeholders to align teams; adjust once packages exist. - For classes, commands, and domain logic, add clear Korean comments to support Korean readers and future maintainers. ## Commit & Pull Request Guidelines + - Git history is minimal and does not define a strict convention; use short, imperative messages (e.g., "Fix map cache loading"). - PRs should include a concise description, testing notes/commands, and screenshots for UI changes. ## Architecture References + - Overview: `docs/architecture/overview.md`. - Legacy engine map: `docs/architecture/legacy-engine.md`. - TypeScript rewrite plan: `docs/architecture/rewrite-plan.md`. - Runtime and build profiles: `docs/architecture/runtime.md`. ## Documentation Workflow + - When AI proposes future improvements or expansions, record them in `docs/architecture/todo.md` with an "AI suggestion" label.