# 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.

---

## 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 (Yudao Cloud fork + 13 game business modules) | Java 17 + Spring Cloud Alibaba + MySQL + Redis + **new-api gateway (generation mainline) + AgentScope 2.x (agentic infra, HJ-AGI-001)**; ~~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 (yudao-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](.agents/knowledge/tech-decisions.md))** + 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 (yudao fork + game-module-*; see game-cloud/.agent)
├── game-admin/                # Admin console frontend (yudao-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 + wave close-out reports + 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)
```

---

## 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/`](.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`](.agents/README.md).

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

| File | One-liner |
|---|---|
| [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md) | Product positioning, the 13 modules & their dependencies, three-repo/three-frontend architecture (distilled) |
| [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md) | Tech stack & key selection rationale (Yudao/Dify/OpenGame/in-house Canvas+Cocos-MCP/Prompt governance, etc.) |
| [`.agents/knowledge/mvp-scope-and-milestones.md`](.agents/knowledge/mvp-scope-and-milestones.md) | The MVP's 55 P0 product-feature scope, milestones & acceptance metrics |
| [`.agents/knowledge/glossary.md`](.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`](.agents/rules/engineering-conventions.md) | Naming / layering / API paths / error codes / commits / PR conventions |
| [`.agents/rules/security-and-reliability.md`](.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`](.agents/skills/add-business-module.md) | Standard steps to add a game-module business module |
| [`.agents/skills/add-game-template.md`](.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`](.agents/skills/ai-generation-pipeline.md) | AI generation pipeline (Dify + OpenGame + aigc shell) dev handbook |
| [`.agents/skills/cheap-model-game-generation.md`](.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/prompt-governance.md`](.agents/skills/prompt-governance.md) | Prompt as the 8th contract: Registry / load-inject / eval gates / HITL governance |
| [`.agents/skills/runtime-and-multichannel.md`](.agents/skills/runtime-and-multichannel.md) | Runtime packaging, sandbox, SDK & multi-channel export handbook |
| [`.agents/skills/contract-first-development.md`](.agents/skills/contract-first-development.md) | Contract-first: aligning API/DB/SDK/event contracts & decoupling parallel work |
| [`.agents/skills/wave-close-checklist.md`](.agents/skills/wave-close-checklist.md) | Wave close-out 7-step checklist — the single executable list all close-out iron rules point to |
| [`.agents/skills/staging-ops.md`](.agents/skills/staging-ops.md) | Staging ops recipes: machine roles / code sync / backend redeploy / build gates / smoke gate |
| [`.agents/skills/ui-walkthrough-cdp.md`](.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`](.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) |

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

| File | One-liner |
|---|---|
| [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md) | Full protocol: take task → analyze → review → execute → verify → distill |
| [`.agents/workflows/mvp-execution-orchestration.md`](.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`](.agents/workflows/ai-development-protocol.md).

1. **Read before acting**: for any task with real complexity, first read [`.agents/knowledge/`](.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.

---

## 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`](.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`](.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`](.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):**

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