> **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.
> **本项目以 AI 驱动开发的方式构建。** 无论你是 AI agent 还是人类工程师,每项任务都从这里开始。
**造梦AI = an AI-driven, mass-market platform for game creation and monetization.**
**绘境AI = 一个 AI 驱动、面向大众市场的游戏创作与变现平台。**
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.
- **零技能**用户可以从一句话构建出一款 **可上线、可变现** 的轻量小游戏;
- **玩家**在类短视频的"游戏 feed"里发现游戏并即点即玩;
- **平台**通过三条线变现:广告分成 / 订阅会员 / B 端定制。
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.
| P0 产品功能覆盖 | **55/55 P0 产品功能可验证**(Doc A 产品范围) | 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.1 Three business codebases (now subdirectories of this monorepo; split into independent repos later)
### 3.1 三个业务代码库(目前是本 monorepo 的子目录;后续拆为独立仓)
> **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.
| **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) |
> **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.
Docs fall into **two layers** — a reading principle, not new directories (classification / distill-gate rules in [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) §10.6; rationale in`docs/brainstorms/2026-06-17-文档体系重构-requirements.md`):
- **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/`).
- **更深一层**的子系统现行架构(生成主线 SAA 16 节点图 / 引擎与运行时 / 渠道发行 / studio 前端设计体系 / 变现与单位经济 等)→ `docs/agent-specs/` 下的 canonical 活档,导航见 [`docs/agent-specs/_index.md`](docs/agent-specs/_index.md)。
---
## 4. Required Reading Order Before Any Task
## 4. 任何任务开工前的必读顺序
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.
> 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.**
| [`.agents/skills/wave-close-checklist.md`](.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 维护) |
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.
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`](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)
## 7. 知识累积机制(同样是硬约束)
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:
`.agents/` 的目的,是让团队在长期开发中 **复利式累积能力**,持续抬高 AI 驱动开发的 **能力、准确度与稳定性**。因此:
- **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)
## 8. 效率原则(复利)
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)):
AI 驱动开发应当"**越做越快**"—— 把每一份产出蒸馏成可复用资产,让效率随工作推进而复利累积。8 条核心策略(见 [`.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.
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.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
zizi