codex와 함께하는 AGENTS.md 작성하기
This commit is contained in:
@@ -1,5 +1,9 @@
|
||||
# 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.
|
||||
|
||||
## 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`).
|
||||
@@ -19,6 +23,56 @@
|
||||
- Tests: PHPUnit in `legacy/tests/`, TypeScript tests in `legacy/hwe/test-ts/`.
|
||||
- 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/logic`: pure game logic with DI/interfaces for external dependencies.
|
||||
- `/app/gateway-frontend`: Gateway UI application.
|
||||
- `/app/gateway-api`: Gateway backend service.
|
||||
- `/app/game-frontend`: Game UI application.
|
||||
- `/app/game-api`: Game backend service per server profile.
|
||||
- `/app/game-engine`: Game engine / turn daemon per server profile.
|
||||
- `/tools/build-scripts`: build and deployment scripts.
|
||||
|
||||
## Planned Runtime & Tooling
|
||||
- Backend: Node.js + Fastify, with Prisma ORM.
|
||||
- API: tRPC + zod.
|
||||
- Frontend: Vue 3, Pinia, Vue Router, TailwindCSS, Vite.
|
||||
- Data: PostgreSQL; sessions backed by Redis.
|
||||
- Testing: Vitest.
|
||||
- Package manager: pnpm (workspace-based monorepo).
|
||||
- Build output: server builds emitted to `/dist/{serverName}` 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.
|
||||
- `pnpm -r build`: build all packages/apps.
|
||||
- `pnpm -r dev`: run dev servers where applicable.
|
||||
- `pnpm --filter ./app/game-engine dev`: run a single service by filter.
|
||||
|
||||
## Server Profiles (Planned)
|
||||
- `che`, `kwe`, `pwe`, `twe`, `nya`, `pya`
|
||||
|
||||
## 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".
|
||||
- Scenarios define maps, NPCs, initial resources; scenario loading separated to allow future modding.
|
||||
- "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.
|
||||
|
||||
## Build, Test, and Development Commands
|
||||
Run commands from `legacy/` unless noted.
|
||||
- `composer install` installs PHP dependencies.
|
||||
@@ -32,12 +86,14 @@ Run commands from `legacy/` unless noted.
|
||||
- `npm run test-ts` runs TypeScript tests only.
|
||||
|
||||
## Coding Style & Naming Conventions
|
||||
- Indentation: 4 spaces, no tabs; line length ~120
|
||||
- PHP modules follow PSR-4 in `legacy/src/sammo/`.
|
||||
- Legacy endpoints are named by role: JSON handlers `legacy/hwe/j_*.php`, views `legacy/hwe/v_*.php`, admin pages `legacy/hwe/_admin*.php`.
|
||||
- Vue components use PascalCase filenames (e.g., `legacy/hwe/ts/components/MapViewer.vue`).
|
||||
- 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`.
|
||||
- Vue components: PascalCase filenames; composables use `useX` naming.
|
||||
- Use `camelCase` for variables/functions and `PascalCase` for classes/types.
|
||||
- Legacy concepts may use Korean identifiers; preserve Korean naming when it improves maintainability.
|
||||
- Hybrid naming is acceptable (e.g., `use전투규칙`, `use도시상태`) when the prefix is conventional but the domain term is Korean.
|
||||
|
||||
## 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.
|
||||
- Avoid committing secrets; use templates in `legacy/f_install/templates/` and settings files under `legacy/hwe/d_setting/` as references.
|
||||
|
||||
Reference in New Issue
Block a user