games-development-ai/AGENTS.md

AGENTS.md — 造梦AI Project · Agent Entry Point

This project is built with AI-driven development. Whether you are an AI agent or a human engineer, start every task here. This file is the single source of truth. It answers both "what this project is" (positioning / goals / directory) and "how to work in it" (what to read first, where to look, what rules to obey, how to feed learnings back). CLAUDE.md simply imports this file via @AGENTS.md; there is no separate project doc to keep in sync.

---

1. Project Positioning

造梦AI = an AI-driven, mass-market platform for game creation and monetization.

Core thesis:

• Zero-skill users can build a launchable, monetizable lightweight mini-game from a single sentence;
• Players discover and instantly play games in a short-video-style "game feed";
• The platform monetizes through three lines: ad revenue share / subscription membership / B-side custom work.

Differentiation moat = a "full closed loop" of generation + traffic + monetization. Most competitors stop at a "generation tool"; 造梦AI links "can build it → people play it → it earns money" into one chain. The real moat is not the generation engine (large models will catch up) but four layers: data, network effects, assets, and compliance.

---

2. Project Goals (MVP Phase)

MVP goal: deliver a full-chain closed loop that seed users can trial — create → generate → preview → publish → review → game feed → play → interact → ads → revenue → telemetry → recommendation optimization.

Key quantitative targets:

Metric	Target	Source
AI generation success rate	≥ 80% (based on 3–5 templates)	MVP execution spec
Game-feed first-screen load	P75 < 3s	MVP execution spec
Service availability	≥ 99.5%	Availability target
MVP infrastructure cost	< ¥5,000/month (investor edition ≈ ¥4,300/month, ~¥50k/year)	Investor edition
P0 product-feature coverage	55/55 P0 product features verifiable (Doc A product scope)	Three-Doc Suite Doc A/C

Two roadmaps coexist — do not mix them:

• Investor edition (HJ-ARCH-002): 5-person core team + ¥4,300/month infra + 11-week MVP, emphasizing capital efficiency and window-of-opportunity validation.
• MVP execution spec (HJ-MVP-SPEC-001): 10 people × 3 weeks (15 working days), emphasizing contract-first + five-station parallelism. Acceptance = the 55 P0 product features in Doc A; workload ≈ 137 technical items.
• Generation success rate: use the execution spec's ≥80% (the investor edition gives no direct number). Cite metrics against the corresponding document.

Daily-default = the MVP execution-spec edition (10 people × 3 weeks / 55 P0 / ≈137 technical items); the investor edition is for external / capital-efficiency framing only, not the day-to-day execution baseline. This §1–2 IS the single source of truth for the top-level objective anchor (current MVP objective = the one-line full-chain closed loop above). Detail homes — docs/mvp/goals.md (charter), .agents/knowledge/mvp-scope-and-milestones.md (55 P0 detail), docs/agent-specs/战略与合规.md (moat / compliance) — expand from here via pointer; do not stand up a parallel objective doc.

---

3. Project Directory

3.1 Three business codebases (now subdirectories of this monorepo; split into independent repos later)

Status (2026-06-11): all three codebases live in this repo as game-cloud/, game-admin/, game-studio/ (monorepo-first, split later — see memory monorepo-first-split-later). The stack column below is blueprint-level: the MVP generation mainline is template-driven via the new-api gateway (Dify/OpenGame downgraded to long-term enhancements, C2 ruling; RocketMQ/Nacos are future-state, not deployed in MVP) — see .agents/knowledge/tech-decisions.md §4.

Codebase	Role	Tech stack
game-cloud	Backend (Huijing Cloud fork + 13 game business modules)	Java 17 + Spring Cloud Alibaba + MySQL + Redis + new-api gateway (generation mainline) + SAA(Spring AI Alibaba v1.1.2.2)裸图编排 (HJ-AGI-002；short-term SAA-only，AgentScope 降 long-term premium 独立轨); Dify/OpenGame downgraded long-term & never deployed, RocketMQ/Nacos future-state — none of these four are in the MVP runtime
game-admin	Admin console frontend (operations / admins)	Vue3 + Element Plus (huijing-ui-admin-vue3 fork)
game-studio	Product frontend (creators + players)	Vue3 + Vant + LittleJS 增强发行版(引擎+能力插件库,Tier1;旧「自研 Canvas Runtime <15KB」已于 2026-06-12 废除,见 .agents tech-decisions §1.1) + WanxiangGameSDK; 3D / standalone App are longer-term tiers

Note (naming distinction): Wave3 adds a studio business module inside the backend game-cloud (creation-flow orchestration, error-code segment 112 / Flyway V8). This is distinct from the product frontend repo game-studio in the table above — the former is a backend orchestration module, the latter is a Vue3 frontend repo. Do not confuse them.

3.2 Current repo (monorepo) directory structure

games-development-ai/
├── CLAUDE.md                  # Imports @AGENTS.md (redirects to the single entry below)
├── AGENTS.md                  # THIS FILE: project overview + how to work here (single source of truth)
├── contracts/                 # The 8 contract classes (API yaml / DB Flyway / SDK / GamePackage / events / Dify IO / ad-slot / prompts) — cross-end single source of truth
├── game-cloud/                # Backend (huijing fork + game-module-*; see game-cloud/.agent)
├── game-admin/                # Admin console frontend (huijing-ui-admin-vue3 fork)
├── game-studio/               # Product frontend (creators + players; see game-studio/.agent)
├── deploy/                    # Deploy & smoke-gate scripts (smoke-test.sh)
├── docs/
│   ├── architecture/          # 6 architecture docs (investor / tech-decision / dev-team editions + Three-Doc Suite: product requirements · technical architecture & modules · requirement-module mapping)
│   ├── agent-specs/           # Review/execution specs + close-out reports + _index.md (活地图·先读,辨活/死/被谁推翻) + agent-loop orchestrator & runs (see orchestrator/.agent)
│   ├── superpowers/specs/     # Execution-level specs such as the MVP execution spec
│   ├── mvp/                   # Living ledgers: progress ledger / battle list (+history archive) / gate board / unit-economics model
│   └── memorys/               # (Legacy) early task snapshots — superseded by close-out reports under agent-specs/; no longer growing
├── docs-design/               # Product / visual design materials
└── .agents/                   # Agent capability hub (knowledge/rules/skills/workflows)

3.3 Two-layer documentation & retrieval (2026-06-17 doc-system refactor)

Docs fall into two layers — a reading principle, not new directories (classification / distill-gate rules in .agents/rules/engineering-conventions.md §10.6; rationale in docs/brainstorms/2026-06-17-文档体系重构-requirements.md):

• Curated layer (few & current · read it = current truth) — one SoT per concept:
  • Top-level objective / positioning → this file §1–2 (the MVP objective anchor)
  • Product WHAT / technical HOW / mapping → Doc A/B/C (§4 table)
  • Cross-cutting progress + 13-module completion → docs/mvp/MVP进度总账.md (module progress single SoT = its §2 matrix)
  • Each subsystem's current architecture → the canonical living docs under docs/agent-specs/ (undated topic names; see _index.md)
  • Reusable capability / rules / playbooks → .agents/
• Trace layer (accumulate freely · retrieve, don't read linearly) — the front door gives a single retrieval entry, not per-file links:
  • Design / task feeders: docs/brainstorms/ (WHAT), docs/plans/ (HOW), and dated review/execution/report under docs/agent-specs/
  • History / evidence: docs/agent-specs/_archive/, close-out reports
  • Retrieval entry = docs/agent-specs/_index.md (living map) + git grep + frontmatter
• Out of bounds: Claude auto-memory (~/.claude/projects/.../memory/, engine-managed · outside the repo · per-session private) — a personal accelerator only; the repo is the authoritative source, and anything reusable must be distilled back into .agents/ to count.
• Dead store: docs/memorys/ (legacy, read-only, no longer growing; new traces go to docs/brainstorms/ + docs/plans/).

---

4. Required Reading Order Before Any Task

The 5 documents below form a complete picture of the project. On first onboarding or for architecture-level tasks, read them in order; for day-to-day development, prefer the distilled versions under .agents/knowledge/ and trace back to the original long docs only when you need detail.

Order	Document	Role
1	docs/architecture/系统概要设计-投资人版.md	Business positioning, capital efficiency, moat & window of opportunity
2	Three-Doc Suite: docs/architecture/产品需求清单.md (Doc A · product WHAT) / docs/architecture/技术架构与模块.md (Doc B · technical HOW · 13 modules) / docs/architecture/需求模块映射.md (Doc C · RTM)	Product requirements / technical modules / M:N mapping (replaces the old "business capability overview")
3	docs/architecture/系统概要设计-技术决策版.md	Full technical-decision picture (architecture baseline)
4	docs/architecture/系统概要设计-开发团队版.md	Day-to-day dev handbook（⚠️ target-state design: env/commands diverge from reality — follow .agents/rules + docs/mvp/MVP进度总账.md instead; see the in-doc status banner, 2026-06-10 audit）
5	docs/superpowers/specs/mvp-execution-spec-design.md	MVP execution spec: 10 people × 3 weeks, contract-first (acceptance = 55 P0 product features / workload ≈ 137 technical items, already synced in the body)

Tip: the original docs are long; reading them in full slows tasks down. The distilled versions live in .agents/knowledge/ and are the default day-to-day entry point.

---

5. .agents/ Directory Navigation

.agents/ is the project's "Agent capability hub", split into four categories. Maintenance rules are in .agents/README.md.

knowledge/ — distilled facts & blueprints, answers "what it is"

File	One-liner
.agents/knowledge/product-and-architecture.md	Product positioning, the 13 modules & their dependencies, three-repo/three-frontend architecture (distilled)
.agents/knowledge/tech-decisions.md	Tech stack & key selection rationale (Huijing/Dify/OpenGame/in-house Canvas+Cocos-MCP/Prompt governance, etc.)
.agents/knowledge/mvp-scope-and-milestones.md	The MVP's 55 P0 product-feature scope, milestones & acceptance metrics
.agents/knowledge/glossary.md	Glossary (game feed / GameConfig / Manifest / quality score, etc.)

rules/ — hard constraints, answers "how it must be"

File	One-liner
.agents/rules/engineering-conventions.md	Naming / layering / API paths / error codes / commits / PR conventions
.agents/rules/security-and-reliability.md	Security baseline, idempotency, timeout & retry, compliance & reliability constraints

skills/ — reusable playbooks, answers "how to do a class of thing"

File	One-liner
.agents/skills/add-business-module.md	Standard steps to add a game-module business module
.agents/skills/add-game-template.md	New gameplay-template onboarding recipe (contract→prompt→runtime→backend→orchestrator→five-level acceptance gates)
.agents/skills/ai-generation-pipeline.md	AI generation pipeline (Dify + OpenGame + aigc shell) dev handbook
.agents/skills/cheap-model-game-generation.md	Cheap-model game generation (W-G1): worker loop · nine-gate real-play harness · design-agent self-produced gatespec · cost/model selection · 5 pitfalls (HJ-GEN-001 proven)
.agents/skills/saa-graph-orchestration.md	SAA bare-StateGraph generation orchestration: topology / add-node / new-api (strip /v1) / checkpoint (incl. saved_at no-tiebreaker framework pitfall + explicit checkPointId fix) / observation / minimal dep set / dispatcher contract / gates (HJ-AGI-002 proven)
.agents/skills/prompt-governance.md	Prompt as the 8th contract: Registry / load-inject / eval gates / HITL governance
.agents/skills/runtime-and-multichannel.md	Runtime packaging, sandbox, SDK & multi-channel export handbook
.agents/skills/contract-first-development.md	Contract-first: aligning API/DB/SDK/event contracts & decoupling parallel work
.agents/skills/wave-close-checklist.md	Wave close-out 8-step checklist — the single executable list all close-out iron rules point to (step 8 = spec 退役/分层 + _index 维护)
.agents/skills/staging-ops.md	Staging ops recipes: machine roles / code sync / backend redeploy / build gates / smoke gate
.agents/skills/ui-walkthrough-cdp.md	Real-UI walkthrough via CDP on mini-desktop (studio/admin) + bridge probe
.agents/skills/game-e2e-cdp-harness.md	Canvas-game e2e evidence harness: orchestration shape / driver six rules / ship red-lines / four-piece evidence (proven on T1b-α, reused by W-G1)
.agents/skills/doc-organizer.md	文档整理助手（手动触发）：增量(上次清理→现在)·两阶段审批门——发起分析 Workflow→编清理计划→评审→创始人批准后才执行；三轴=过期档清理/核心设计档措辞对齐现行真相/主任务总账回填；配 .agents/tools/doc-organizer.{sh,-analyze.mjs,-state.json}

workflows/ — meta-processes, answers "how to take on a task"

File	One-liner
.agents/workflows/ai-development-protocol.md	Full protocol: take task → analyze → review → execute → verify → distill
.agents/workflows/mvp-execution-orchestration.md	MVP 10-Agent × 3-week execution orchestration + 8 compounding-efficiency strategies

---

6. Working Protocol (Hard Constraints)

These are condensed clauses; the full process is in .agents/workflows/ai-development-protocol.md.

1. Read before acting: for any task with real complexity, first read .agents/knowledge/ and the relevant docs/, align on facts, then start.
2. Review first for complex / high-risk work: tasks that cross modules, change user-visible behavior, or touch external services / payments / data must go review edition → two review rounds → then execute; do not write code directly.
3. Evidence rule: distinguish "verified fact / inference / assumption". Without verification evidence, never claim "done / fixed / passing / no issues". Anything runnable (tests, build, lint, smoke) must be run.
4. Minimal change: only touch code directly related to the current requirement, reuse existing patterns, and do not casually refactor unrelated naming / directories / formatting.
5. Chinese comments: all code must carry complete Simplified Chinese comments; external interactions, core implementation, and error paths must have traceable logs.
6. Contract-first: for interface / data-structure changes, update the contract first (contracts/ and the -api packages), then implement, and notify stakeholders.
7. No orphan designs: any new feature, data structure, API, domain model, or workflow must come with its user-facing entry point, usage path, failure modes, and acceptance criteria — no API without an entry point, no isolated capability without a product flow, no stitched-together solution that merely adapts one spec to another.
8. Dual (bilateral) review gate for plan docs (2026-06-18, founder): creating a new brainstorm / plan document — including folding new units into an existing living plan — must pass a Codex + Opus dual review before close-out; if Codex is unavailable, fall back to Opus alone. Run the two in parallel (codex:codex-rescue + an Opus adversarial document review), feed the design premises so intentional decisions aren't flagged as defects, fix in-document findings, and list cross-document findings as close-out TODOs.
9. Internal-network phase: decisions & keys live in project docs, not env vars (2026-06-18, founder): during the internal-network phase, all decisions and all keys/credentials go into project documentation (internal Tailscale addresses / keys / tokens are explicitly allowed in the repo). Keys → docs/内网凭据与端点.md (single source of truth — NEWAPI_KEY / endpoints / machines live there). Need a key? Read that doc — do NOT ask the founder again, and do NOT depend on environment variables. Decisions → the relevant plan / living doc, never left only in chat.

---

7. Knowledge Accumulation Mechanism (Also a Hard Constraint)

The purpose of .agents/ is to let the team compound capability over long-term development, continuously raising the capability, accuracy, and stability of AI-driven development. Therefore:

• After every valuable task, you must write reusable output back into the matching .agents/ directory:
  • New facts / blueprint knowledge → knowledge/
  • New hard constraints / pitfall red-lines → rules/
  • New reusable operating playbooks → skills/
  • Process-level improvements → workflows/
• Check for duplicates before adding: prefer updating an existing file over creating a new one; fix or delete stale content immediately.
• When changing .agents/, also update the index and cross-links in .agents/README.md to keep navigation consistent.
• Keep all content in Simplified Chinese, single-topic, concise, and quickly searchable.

A task with no distillation is a "one-off consumption"; with distillation, the next similar task can build on existing results faster and more accurately.

---

8. Efficiency Principles (Compounding)

AI-driven development should get "faster as it goes" — distill every output into a reusable asset so efficiency compounds as work progresses. The 8 core strategies (see .agents/workflows/mvp-execution-orchestration.md):

1. Golden template first: perfect one module first, then clone its skeleton for the rest.
2. Contract-first: lock contracts (API/DB/SDK/event) before any parallel work.
3. Reuse over rebuild(三级次序): before writing code, search in order — ① 仓内(skills/, knowledge/, existing code), ② 生态现货(npm/PyPI/GitHub,强制 prior-art 步,见 .agents/rules/build-vs-buy.md), ③ 而后才许自研; 基建类组件另须先过 Build-vs-Buy 前置门。
4. Verification gates up front: TDD + gates + pre-completion verification to catch errors early and prevent rework (rework is the #1 efficiency killer).
5. Parallel boundary = module boundary: zero shared state between agents, worktree isolation, interaction only through contracts.
6. .agents compounding distillation: write learnings back on every delivery (see §7).
7. Cache expensive steps: skip the LLM on a matching Prompt hash; cache builds / artifacts.
8. Reproducible orchestration: freeze fan-out + verify into Workflow scripts.

---

9. gstack Toolset (Global Skills)

gstack is a set of global slash-skills (browse / review / QA / deploy / docs, etc.), installed per developer machine under ~/.claude/skills/gstack. Once installed, everything is triggered through the single /gstack entry point from any project — sub-skills are not registered individually; the agent reads ~/.claude/skills/gstack/<name>/SKILL.md on demand and follows it.

Install (each member runs once):

git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack \
  && cd ~/.claude/skills/gstack && ./setup