zizi-al/games-development-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 整合项目入口为 AGENTS.md 单一事实源 + 英文化

Browse Source 
- AGENTS.md 升级为单一事实源：并入项目定位/目标/目录 + 新增「角色与协作原则」，整体英文化
- CLAUDE.md 精简为仅 @AGENTS.md 导入，消除双文档同步负担
- .agents/README.md 交叉链接同步指向 AGENTS.md 唯一入口

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
zizi 2026-06-09 10:57:23 +00:00
parent 6add6c771a
commit 6cf1515e98
3 changed files with 162 additions and 141 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.agents/README.md
View File

@ -2,7 +2,7 @@
> 本目录沉淀并积累项目的**全部 Agent 能力、技能与规则**，让团队在长期开发中**复利式积累知识、流程与能力**，持续提升 AI 驱动开发的**能力、准确率与稳定性**。
>
> 工作入口指南见 [`../AGENTS.md`](../AGENTS.md)；项目定位/目标/目录见 [`../CLAUDE.md`](../CLAUDE.md)。
> 工作入口、项目定位/目标/目录均见 [`../AGENTS.md`](../AGENTS.md)（项目唯一入口）；`CLAUDE.md` 仅以 `@AGENTS.md` 导入它。
---

232
AGENTS.md
View File

@ -1,128 +1,216 @@
# AGENTS.md — 造梦AI 项目 Agent 工作入口
# AGENTS.md — 造梦AI Project · Agent Entry Point
> **本项目采用 AI 驱动开发。** 无论你是 AI Agent 还是工程师，开始任何任务前都从这里进入。
> 本文件回答"**怎么在本项目里干活**"：先读什么、去哪查、守什么规矩、如何把经验沉淀回来。
> 项目"是什么/目标/目录"见 [`CLAUDE.md`](CLAUDE.md)。
> **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
下面 5 份文档构成对项目的完整认知。**首次接手或做架构级任务时按序通读**；日常开发**优先读 [`.agents/knowledge/`](.agents/knowledge/) 下的蒸馏版**，需要细节再回溯原始长文档。
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 |
|---|---|---|
| 1 | `docs/architecture/系统概要设计-投资人版.md` | 商业定位、资本效率、壁垒与窗口期 |
| 2 | 三文档套件：`docs/architecture/产品需求清单.md`(Doc A·产品WHAT) / `docs/architecture/技术架构与模块.md`(Doc B·技术HOW·13模块) / `docs/architecture/需求模块映射.md`(Doc C·RTM) | 产品需求 / 技术模块 / M:N 映射（取代原"业务能力全景"） |
| 3 | `docs/architecture/系统概要设计-技术决策版.md` | 技术决策全貌（架构基线） |
| 4 | `docs/architecture/系统概要设计-开发团队版.md` | 日常开发手册：环境/目录/规范/联调/提交 |
| 5 | `docs/superpowers/specs/mvp-execution-spec-design.md` | MVP 执行 spec：10 人×3 周、契约先行（验收=55 项 P0 产品功能 / 工作量≈137 技术项，正文已同步）|
| 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 |
> 提示：原始文档很长，直接全读会拖慢任务。**蒸馏版位于 `.agents/knowledge/`，是日常默认入口。**
> **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.
---
## 二、`.agents/` 目录导航
## 3. Project Directory
`.agents/` 是项目的"Agent 能力中枢"，分四类。维护规则见 [`.agents/README.md`](.agents/README.md)。
### 3.1 Three independent Git repos (business code repos; not yet contained in this repo)
### knowledge/ —— 事实与蓝图蒸馏，回答"**是什么**"
| 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](.agents/knowledge/tech-decisions.md)) |
| 文件 | 一句话说明 |
> **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/`](.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: environment / directory / conventions / integration / commits |
| 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) | 产品定位、13 模块与依赖、三仓三端架构蒸馏 |
| [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md) | 技术栈与关键选型理由（Yudao/Dify/OpenGame/自研Canvas+Cocos-MCP/Prompt 治理 等） |
| [`.agents/knowledge/mvp-scope-and-milestones.md`](.agents/knowledge/mvp-scope-and-milestones.md) | MVP 的 55 项 P0 产品功能范围、里程碑与验收指标 |
| [`.agents/knowledge/glossary.md`](.agents/knowledge/glossary.md) | 术语表（游戏流/GameConfig/Manifest/质量分等） |
| [`.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/ —— 硬约束，回答"**必须怎样**"
### rules/ — hard constraints, answers "**how it must be**"
| 文件 | 一句话说明 |
| File | One-liner |
|---|---|
| [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) | 命名/分层/API 路径/错误码/提交/PR 等工程规范 |
| [`.agents/rules/security-and-reliability.md`](.agents/rules/security-and-reliability.md) | 安全基线、幂等、超时重试、合规与可靠性约束 |
| [`.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/ —— 可复用操作手册（playbook），回答"**怎么做某类事**"
### 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) | 新增一个 game-module 业务模块的标准步骤 |
| [`.agents/skills/ai-generation-pipeline.md`](.agents/skills/ai-generation-pipeline.md) | AI 生成链路（Dify + OpenGame + aigc 壳）开发手册 |
| [`.agents/skills/runtime-and-multichannel.md`](.agents/skills/runtime-and-multichannel.md) | 运行时打包、沙箱、SDK 与多渠道导出手册 |
| [`.agents/skills/contract-first-development.md`](.agents/skills/contract-first-development.md) | 契约先行：API/DB/SDK/事件契约对齐与并行解耦 |
| [`.agents/skills/add-business-module.md`](.agents/skills/add-business-module.md) | Standard steps to add a game-module business module |
| [`.agents/skills/ai-generation-pipeline.md`](.agents/skills/ai-generation-pipeline.md) | AI generation pipeline (Dify + OpenGame + aigc shell) dev handbook |
| [`.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 |
### workflows/ —— 元流程，回答"**如何承接一个任务**"
### 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) | 任务承接→分析→评审→执行→验证→沉淀的完整协议 |
| [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md) | MVP 10-Agent×3周 执行编排 + 8 条复利提效策略 |
| [`.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)
以下为精炼条款，详细流程见 [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md)。
These are condensed clauses; the full process is in [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md).
1. **先读再动**：遇到有真实复杂度的任务，先读 [`.agents/knowledge/`](.agents/knowledge/) 与相关 `docs/`，对齐事实再动手。
2. **复杂/高风险先评审**：跨模块、改动用户可见行为、或涉及外部服务/支付/数据的任务，**先出评审版 → 两轮评审 → 再执行**，不要直接写代码。
3. **证据规则**：区分"已验证事实 / 推断 / 假设"。**没有验证证据，不得声称"完成 / 已修复 / 通过 / 无问题"。** 跑得了的（测试、构建、lint、冒烟）必须跑。
4. **最小变更**：只改与当前需求直接相关的代码，复用既有模式，不顺手重构无关命名/目录/格式。
5. **中文注释**：所有代码必须配完整简体中文注释；外部交互、核心实现、错误路径要有可追溯日志。
6. **契约先行**：接口/数据结构变更先更新契约（`contracts/` 与 `-api` 包），再实现，并通知相关方。
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. Knowledge Accumulation Mechanism (Also a Hard Constraint)
`.agents/` 的目的，是让团队在长期开发中**复利式积累能力**，持续提升 AI 驱动开发的**能力、准确率与稳定性**。因此：
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/` 对应目录：**
- 新的事实/蓝图认知 → `knowledge/`
- 新的硬约束/踩坑红线 → `rules/`
- 新的可复用操作套路 → `skills/`
- 流程层面的改进 → `workflows/`
- **先查重再新增**：能更新现有文件就不要新建；过时内容即时修正或删除。
- **变更 `.agents/` 时，同步更新 [`.agents/README.md`](.agents/README.md) 的索引与相关交叉链接**，保持导航一致。
- 一切内容用**简体中文**，保持单一主题、精炼、可快速检索。
- **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 驱动开发要"**越做越快**"——把每次产出沉淀为可复用资产，让效率随推进复利增长。8 条核心策略（详见 [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md)）：
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. **黄金模板先行**：先把一个模块做到完美，其余克隆骨架。
2. **契约先行**：并行开发前必锁契约（API/DB/SDK/事件）。
3. **复用优先于新建**：写代码前先搜 `skills/`、`knowledge/` 与既有代码，避免重复造轮子。
4. **验证门禁前置**：TDD + 门禁 + 完成前验证，早拦错、防返工（返工是头号效率杀手）。
5. **并行边界 = 模块边界**：Agent 间零共享状态、worktree 隔离、只经契约交互。
6. **`.agents` 复利沉淀**：每次交付回写经验（见第四节）。
7. **昂贵步骤缓存**：相同 Prompt hash 命中跳过 LLM；构建/产物缓存。
8. **可复现编排**：用 Workflow 脚本固化 fan-out + verify。
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.
---
## 六、gstack 工具集（全局技能）
## 9. gstack Toolset (Global Skills)
gstack 是一套全局斜杠技能集（浏览 / 评审 / QA / 部署 / 文档 等），**按开发者机器安装**到 `~/.claude/skills/gstack`，安装后下列技能即可在任意项目直接调用。
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):**
```bash
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:**
- **所有网页 / 浏览器操作一律走 gstack 的 `/browse` 技能**：导航、抓取、页面巡检、QA 等任何 web 交互都用它。
- **禁止使用 `mcp__claude-in-chrome__*` 工具**：一律改用 `/browse`（或相应的 gstack 浏览技能）。
- **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.
**可用 gstack 技能：**
**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`
> 注：gstack 为开发者个人级工具，安装与个人偏好在各自 `~/.claude/` 配置；本节仅为团队成员在本项目内提供一致的使用入口与约束。
> 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.

69
CLAUDE.md
View File

@ -1,68 +1 @@
# 造梦AI 游戏生态平台
> 本文件只讲三件事：**项目定位、项目目标、项目目录**。
> 工作方式、规范、技能、流程一律见 [`AGENTS.md`](AGENTS.md) 与 [`.agents/`](.agents/)，本文件不重复。
---
## 一、项目定位
**造梦AI = AI 驱动的全民游戏创作与变现生态平台。**
核心命题：
- **零基础**用户用一句话就能做出**可上线、可变现**的轻量小游戏；
- **玩家**像刷短视频一样在"游戏流"里发现并即点即玩；
- **平台**靠广告分成 / 订阅会员 / B 端定制三条线变现。
差异化壁垒 = **生成 + 流量 + 变现"全闭环"**。竞品多停在"生成工具"，造梦把"做得出 → 有人玩 → 赚到钱"接成一条链路；真正护城河不在生成引擎（会被大模型追平），而在数据、网络效应、资产与合规四层壁垒。
---
## 二、项目目标（MVP 阶段）
MVP 目标：交付一个**种子用户可试用的全链路闭环**——创作→生成→预览→发布→审核→游戏流→试玩→互动→广告→收益→遥测→推荐优化。
关键量化指标：
| 指标 | 目标值 | 来源 |
|---|---|---|
| AI 生成成功率 | **≥ 80%**（基于 3-5 个模板） | MVP 执行 spec |
| 游戏流首屏加载 | **P75 < 3s** | MVP 执行 spec |
| 服务可用性 | **≥ 99.5%** | 可用性目标 |
| MVP 基础设施成本 | **< 5000 元/月**（投资人版核算约 ¥4,300/月，年化 ~5 万） | 投资人版 |
| P0 产品功能覆盖 | **55/55 项 P0 产品功能可验证**（Doc A 产品口径）| 三文档套件 Doc A/C |
> **两份路线并存，勿混用：**
> - **投资人版（HJ-ARCH-002）**：**5 人核心团队 + ¥4,300/月基础设施 + 11 周 MVP**，强调资本效率与窗口期验证。
> - **MVP 执行 spec（HJ-MVP-SPEC-001）**：**10 人 × 3 周（15 工作日）**，强调契约先行 + 五工位并行。验收 = Doc A 的 **55 项 P0 产品功能**；工作量 **≈137 技术项**。
> - 生成成功率：**以执行 spec ≥80% 为准**（投资人版未直接给数值）。引用指标时以对应文档为准。
---
## 三、项目目录
### 3.1 三个独立 Git 仓库（业务代码仓，当前仓库尚不含其代码）
| 仓库 | 定位 | 技术栈 |
|---|---|---|
| **game-cloud** | 后端（Yudao Cloud fork + 13 个游戏业务模块） | Java 17 + Spring Cloud Alibaba + MySQL + RocketMQ + Redis + Nacos + Dify + OpenGame |
| **game-admin** | 管理后台前端（运营/管理员用） | Vue3 + Element Plus（yudao-ui-admin-vue3 fork） |
| **game-studio** | 产品端前端（创作者 + 玩家用） | Vue3 + Vant + 自研轻量 Canvas Runtime(<15KB, Tier1) + WanxiangGameSDK；3D/独立App 为远期分层（详见 [.agents tech-decisions §1.1](.agents/knowledge/tech-decisions.md)） |
> **注（命名区分）**：Wave3 后端 game-cloud 内新增 `studio` 业务模块（创作主链路编排，错误码段 112 / Flyway V8），与上表**产品端前端仓 `game-studio`** 是两个东西——前者是后端编排模块，后者是 Vue3 前端仓，勿混淆。
### 3.2 当前仓库（文档仓）目录结构
```
games-development-ai/
├── CLAUDE.md # 本文件：定位/目标/目录
├── AGENTS.md # AI/工程师工作入口指南
├── docs/
│ ├── architecture/ # 6 份架构设计文档（投资人版/技术决策版/开发团队版 + 三文档套件：产品需求清单·技术架构与模块·需求模块映射）
│ ├── agent-specs/ # 执行级 spec（如 Prompt 治理执行版）
│ ├── superpowers/specs/ # MVP 执行 spec 等执行级规格
│ └── memorys/ # 任务历史快照（带日期归档，长期留存）
├── docs-design/ # 产品/视觉设计资料
└── .agents/ # Agent 能力中枢（knowledge/rules/skills/workflows）
```
@AGENTS.md