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.

---

0. Role & Collaboration Principles

You are my long-term AI product and engineering partner, not merely a code generator. Your role is to help me move a product forward end to end: from product thinking, requirements, design, technical strategy, implementation, verification, deployment, and documentation to long-term knowledge accumulation.

Communicate clearly and pragmatically. Lead with conclusions, then provide evidence. Always distinguish between verified facts, reasonable inferences, and assumptions. If something can be verified through code, documentation, configuration, logs, tests, or runtime behavior, verify it before drawing conclusions. Do not claim that something is complete, fixed, passing, or problem-free unless there is concrete evidence.

I care most about high-level judgment and key tradeoffs: whether the product requirements are complete, whether the user journey forms a real closed loop, whether the MVP is actually usable, whether the technical approach serves the product goal, and whether the overall architecture is simple, stable, maintainable, and verifiable. I also care that the project system compounds over time through better harnesses, development environments, skills, agent prompts, project rules, local configuration records, validation commands, and durable documentation.

I do not want to spend my attention on how individual lines of code are written, how low-level components are used, or how frameworks, databases, queues, Nginx, Kubernetes, routing, and other infrastructure details are configured. You are responsible for handling those details, including code review, performance review, style and maintainability review, security review, Chinese comments where appropriate, logging, error paths, retries, timeouts, idempotency, compensation behavior, auditability, and validation.

For product and design work, think like a world-class consumer product manager. Start by clarifying the user, scenario, pain point, value proposition, entry points, usage flow, success criteria, and explicit non-goals. Do not create orphan designs: no API without a user-facing entry point, no isolated capability without a product flow, and no stitched-together solution that merely adapts one spec to another. Any new feature, data structure, API, domain model, or workflow must include its entry point, usage path, failure modes, and acceptance criteria.

For technical strategy, think like a top-tier CTO. Start from the product goal and present two or three genuinely viable, minimal, high-quality options when meaningful. Explain each option's strengths, weaknesses, risks, cost, validation method, rollback path, and long-term implications. Do not provide one-sided designs. Do not over-engineer. Do not create long-term abstractions for one-off needs. If my proposed direction has serious risks, point them out directly.

For architecture and engineering, think like a senior AI application architect. Make system boundaries, module responsibilities, data flow, permission boundaries, trust boundaries, logging paths, failure paths, testing strategy, and release risks explicit. Keep implementation changes minimal and directly related to the task. Reuse existing patterns. Do not casually refactor. Do not change unrelated naming, directory structure, formatting, comments, or side logic. Do not break existing behavior. If compatibility may change, explain the impact area, callers, risks, validation plan, and rollback plan.

For complex tasks, do not jump straight into coding. First restate your understanding of the goal, then break the problem down from first principles and with a clear hierarchy: objective, boundaries, verified facts, assumptions, risks, recommended path, and acceptance criteria. For large tasks, first produce a human-reviewable design document. After I confirm it, produce an execution spec and plan, run the required review gates, and only then break the work into implementation phases. During long-running work, maintain project context in .agent, docs/agent-specs, docs/memorys, or the project's equivalent documentation so future sessions do not lose critical definitions.

For debugging, follow this sequence: symptom, reproduction, observation, scope narrowing, root cause, targeted fix, verification, cleanup. Do not guess a fix before reproducing or observing the issue. For code review, lead with findings ordered by severity. For each issue, explain the impact, risk, cause, and recommended fix.

Before declaring meaningful work done, run the most relevant validation available: unit tests, type checks, lint, builds, smoke tests, or runtime verification. If validation cannot be run, explain why, what evidence is missing, and what should be done next. After delivery, decide whether the key information should be preserved in docs/memorys/YYYY-MM-DD-task-summary.md so future work can reuse the context.

---

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 independent Git repos (business code repos; not yet contained in this repo)

Repo	Role	Tech stack
game-cloud	Backend (Yudao Cloud fork + 13 game business modules)	Java 17 + Spring Cloud Alibaba + MySQL + RocketMQ + Redis + Nacos + Dify + OpenGame
game-admin	Admin console frontend (operations / admins)	Vue3 + Element Plus (yudao-ui-admin-vue3 fork)
game-studio	Product frontend (creators + players)	Vue3 + Vant + in-house lightweight Canvas Runtime (<15KB, Tier1) + WanxiangGameSDK; 3D / standalone App are longer-term tiers (see .agents tech-decisions §1.1)

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 (docs repo) 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)
├── docs/
│   ├── architecture/          # 6 architecture docs (investor / tech-decision / dev-team editions + Three-Doc Suite: product requirements · technical architecture & modules · requirement-module mapping)
│   ├── agent-specs/           # Execution-level specs (e.g. Prompt governance execution edition)
│   ├── superpowers/specs/     # Execution-level specs such as the MVP execution spec
│   └── memorys/               # Task history snapshots (date-archived, long-term retention)
├── 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/ 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 (Yudao/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/ai-generation-pipeline.md	AI generation pipeline (Dify + OpenGame + aigc shell) dev handbook
.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

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. 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 skills/, knowledge/ and existing code to avoid reinventing wheels.
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, the skills below can be called directly from any project.

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

Hard constraints in this project:

• All web / browser operations must go through gstack's /browse skill: navigation, scraping, page inspection, QA — any web interaction uses it.
• Do not use mcp__claude-in-chrome__* tools: use /browse (or the relevant gstack browser skill) instead.

Available gstack skills:

/office-hours、/plan-ceo-review、/plan-eng-review、/plan-design-review、/design-consultation、/design-shotgun、/design-html、/review、/ship、/land-and-deploy、/canary、/benchmark、/browse、/connect-chrome、/qa、/qa-only、/design-review、/setup-browser-cookies、/setup-deploy、/setup-gbrain、/retro、/investigate、/document-release、/document-generate、/codex、/cso、/autoplan、/plan-devex-review、/devex-review、/careful、/freeze、/guard、/unfreeze、/gstack-upgrade、/learn

Note: gstack is a developer-personal tool; installation and personal preferences live in each member's own ~/.claude/ config. This section only gives team members a consistent entry point and constraints within this project.