ae7d78ddde
- tier2 富游戏线 = AgentScope(Python 独立 service) + Phaser；Tier0/1 廉价线 = SAA + LittleJS(产物走 src 源项目) - gamedef json 正废除中(另会话)→ 终态=可维护 src 源项目；gameDefinition 现为迁移中的中间脚手架/债(非已移除) - Cocos 区分：退出 tier2 自治轨改 Phaser；Tier3/3D/渠道导出的 Cocos 保留 - 未来可能两条线收敛入 AgentScope(登记) - 覆盖：顶层图说体系(系统全景/架构/产品/前端图说) + 架构核心(README/产物执行沙箱) + glossary/tech-decisions + AGENTS§3 + mvp(总账/作战清单/可行性方案) + agent-specs(agentic编排-SAA/_index) + 图①svg Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
224 lines
24 KiB
Markdown
224 lines
24 KiB
Markdown
# AGENTS.md — 绘境AI Project · Agent 入口
|
||
|
||
> **本项目以 AI 驱动开发的方式构建。** 无论你是 AI agent 还是人类工程师,每项任务都从这里开始。
|
||
> 本文件是 **single source of truth**。它既回答 **"这个项目是什么"**(定位 / 目标 / 目录),也回答 **"在它里面怎么干活"**(先读什么、去哪里看、要遵守哪些规则、如何把学到的东西反哺回来)。
|
||
> `CLAUDE.md` 只是通过 `@AGENTS.md` 导入本文件;不存在另一份需要同步维护的项目文档。
|
||
|
||
---
|
||
|
||
## 1. 项目定位
|
||
|
||
**绘境AI = 一个 AI 驱动、面向大众市场的游戏创作与变现平台。**
|
||
|
||
核心论点:
|
||
|
||
- **零技能**用户可以从一句话构建出一款 **可上线、可变现** 的轻量小游戏;
|
||
- **玩家**在类短视频的"游戏 feed"里发现游戏并即点即玩;
|
||
- **平台**通过三条线变现:广告分成 / 订阅会员 / B 端定制。
|
||
|
||
差异化护城河 = 生成 + 流量 + 变现的 **"全闭环"**。大多数竞品止步于"生成工具";绘境AI 把"能造出来 → 有人玩 → 能赚钱"串成一条链。真正的护城河不是生成引擎(大模型迟早会追上),而是四层:数据、网络效应、资产、合规。
|
||
|
||
---
|
||
|
||
## 2. 项目目标(MVP 阶段)
|
||
|
||
MVP 目标:交付一条 **种子用户可试用的全链路闭环** —— create → generate → preview → publish → review → game feed → play → interact → ads → revenue → telemetry → recommendation optimization。
|
||
|
||
关键量化目标:
|
||
|
||
| 指标 | 目标 | 出处 |
|
||
|---|---|---|
|
||
| AI 生成成功率 | **≥ 80%**(基于 3–5 个模板) | MVP execution spec |
|
||
| 游戏 feed 首屏加载 | **P75 < 3s** | MVP execution spec |
|
||
| 服务可用性 | **≥ 99.5%** | 可用性目标 |
|
||
| MVP 基础设施成本 | **< ¥5,000/月**(投资人版 ≈ ¥4,300/月,约 ¥50k/年) | 投资人版 |
|
||
| P0 产品功能覆盖 | **55/55 P0 产品功能可验证**(Doc A 产品范围) | Three-Doc Suite Doc A/C |
|
||
|
||
> **两条路线图并存 —— 不要混用:**
|
||
> - **投资人版(HJ-ARCH-002):** **5 人核心团队 + ¥4,300/月基础设施 + 11 周 MVP**,强调资本效率与窗口期验证。
|
||
> - **MVP execution spec(HJ-MVP-SPEC-001):** **10 人 × 3 周(15 个工作日)**,强调 contract-first + 五工位并行。验收 = Doc A 中的 **55 个 P0 产品功能**;工作量 **≈ 137 个技术项**。
|
||
> - 生成成功率:**采用 execution spec 的 ≥80%**(投资人版未给直接数字)。引用指标时要对应到相应文档。
|
||
>
|
||
> **日常默认 = MVP execution-spec 版**(10 人 × 3 周 / 55 P0 / ≈137 技术项);投资人版仅用于对外 / 资本效率叙述,不作为日常执行基线。**本 §1–2 即是顶层目标锚点的 single source of truth**(当前 MVP 目标 = 上面那一行全链路闭环)。明细归宿 —— `docs/mvp/goals.md`(章程)、`.agents/knowledge/mvp-scope-and-milestones.md`(55 P0 明细)、`docs/architecture/运营/合规闸门.md`(护城河 / 合规)—— 从这里通过指针展开;不要另立一份平行的目标文档。
|
||
|
||
---
|
||
|
||
## 3. 项目目录
|
||
|
||
### 3.1 三个业务代码库(目前是本 monorepo 的子目录;后续拆为独立仓)
|
||
|
||
> **状态(2026-06-11):** 三个代码库都 **在本仓** 内,即 `game-cloud/`、`game-admin/`、`game-studio/`(monorepo 先行、后续再拆 —— 见 memory `monorepo-first-split-later`)。下表的技术栈列是蓝图级。**游戏生成现行是两条并存的线**(详见 `.agents/knowledge/tech-decisions.md` §1.1/§4 与 `docs/architecture/架构/生成引擎/`):一条是 **Tier0/1 廉价线** —— 便宜模型经 new-api gateway 由 SAA(Spring AI Alibaba)裸图编排,产物落在 LittleJS 增强发行版上,过九门兜底(早先的"模板驱动 / 填参式"路线已随 W-CLEAN 退役,改为 agent 写码;创始人 2026-06-20 进一步把终态定调为可维护的 `src/` 多文件源工程,当前的 gameDefinition 中间表示只是通往 src/ 的脚手架);另一条是 **tier2 富游戏线** —— 一个自治 ReAct agent 用 AgentScope(Python·独立 service)造现有廉价线做不出的多系统富游戏,产物是真 Phaser 源工程,**现状=待 0号 spike 验证、尚未落代码**。Dify/OpenGame 降为长期增强且从未部署,RocketMQ/Nacos 是 future-state、MVP 不部署 —— 这四者均不在 MVP runtime 中。
|
||
|
||
| 代码库 | 角色 | 技术栈 |
|
||
|---|---|---|
|
||
| **game-cloud** | 后端(Huijing Cloud fork + 13 个游戏业务模块) | Java 17 + Spring Cloud Alibaba + MySQL + Redis + **new-api gateway(生成主线)+ SAA(Spring AI Alibaba v1.1.2.2)裸图编排 (HJ-AGI-002;廉价线 agentic 基建 = SAA-only)**; ~~Dify/OpenGame~~ 降为 long-term 且从未部署, ~~RocketMQ/Nacos~~ future-state —— 这四者均不在 MVP runtime 中。tier2 富游戏线的 AgentScope 是独立 Python service、不在 Java 后端内(见上文 §3.1 banner)。 |
|
||
| **game-admin** | 管理后台前端(运营 / 管理员) | Vue3 + Element Plus(huijing-ui-admin-vue3 fork) |
|
||
| **game-studio** | 产品前端(创作者 + 玩家) | Vue3 + Vant + **LittleJS 增强发行版(引擎+能力插件库,Tier0/1 廉价线;旧「自研 Canvas Runtime <15KB」已于 2026-06-12 废除,见 [.agents tech-decisions §1.1](.agents/knowledge/tech-decisions.md))** + WanxiangGameSDK。**tier2 富游戏线**另用 **AgentScope(Python 自治 agent)+ Phaser** 造多系统富游戏(待 0号 spike 验证、尚未落代码);Cocos 只留 3D / 渠道导出轴(编辑器 + 人在环),3D / 独立 App 属更长期层级。 |
|
||
|
||
> **注(命名区分):** Wave3 在 **后端** game-cloud 内部新增了一个 `studio` 业务模块(创作流编排,错误码段 112 / Flyway V8)。它与上表中的 **产品前端仓 `game-studio`** 是两回事 —— 前者是后端编排模块,后者是 Vue3 前端仓。不要混淆。
|
||
|
||
### 3.2 当前仓(monorepo)目录结构
|
||
|
||
```
|
||
games-development-ai/
|
||
├── CLAUDE.md # 导入 @AGENTS.md(重定向到下面的单一入口)
|
||
├── AGENTS.md # 本文件:项目总览 + 在此如何工作(single source of truth)
|
||
├── contracts/ # 8 个契约类(API yaml / DB Flyway / SDK / GamePackage / events / Dify IO / ad-slot / prompts)—— 跨端的 single source of truth
|
||
├── game-cloud/ # 后端(huijing fork + game-module-*;见 game-cloud/.agent)
|
||
├── game-admin/ # 管理后台前端(huijing-ui-admin-vue3 fork)
|
||
├── game-studio/ # 产品前端(创作者 + 玩家;见 game-studio/.agent)
|
||
├── deploy/ # 部署与 smoke-gate 脚本(smoke-test.sh)
|
||
├── docs/
|
||
│ ├── architecture/ # 设计文档 SoT 根(2026-06-20 域化重构):README 总索引 + 6 域(产品/架构含生成引擎🚧/后端/前端/运营/运维)4 级人读散文树;旧长档归 _archive
|
||
│ ├── agent-specs/ # review/execution specs + close-out reports + _index.md(活地图·先读,辨活/死/被谁推翻)+ agent-loop orchestrator 与 runs(见 orchestrator/.agent)
|
||
│ ├── superpowers/specs/ # execution 级 specs,如 MVP execution spec
|
||
│ ├── mvp/ # 活账本:进度总账 / 作战清单(+历史归档)/ 闸门看板 / 单位经济模型
|
||
│ └── memorys/ # (Legacy)早期任务快照 —— 已被 agent-specs/ 下的 close-out reports 取代;不再增长
|
||
├── docs-design/ # 产品 / 视觉设计材料
|
||
└── .agents/ # Agent 能力中枢(knowledge/rules/skills/workflows)
|
||
```
|
||
|
||
### 3.3 两层文档与检索(2026-06-17 文档体系重构)
|
||
|
||
文档分为 **两层** —— 这是一种阅读原则,而非新目录(分类 / 蒸馏门规则见 [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) §10.6;来由见 `docs/brainstorms/2026-06-17-文档体系重构-requirements.md`):
|
||
|
||
- **策展层(少而准 · 读它 = 当前真相)** —— 每个概念一份 SoT:
|
||
- 顶层目标 / 定位 → 本文件 §1–2(MVP 目标锚点)
|
||
- 产品 WHAT / 技术 HOW / 映射 / 各子系统现行架构 → `docs/architecture/` 6 域设计树(2026-06-20 改根;§4 表,总索引 README)
|
||
- 横切进度 + 13 模块完成度 → `docs/mvp/MVP进度总账.md`(**模块进度单一 SoT = 其 §2 矩阵**)
|
||
- 各子系统的当前架构 → `docs/architecture/` 对应域(2026-06-20 改根;生成引擎子树 🚧 架构演进中);`docs/agent-specs/` 降为留痕 + 生成域演进设计链
|
||
- 可复用能力 / 规则 / playbook → `.agents/`
|
||
- **留痕层(放开累积 · 检索,不要线性通读)** —— 前门给出单一检索入口,而非逐文件链接:
|
||
- 设计 / 任务喂料:`docs/brainstorms/`(WHAT)、`docs/plans/`(HOW),以及 `docs/agent-specs/` 下带日期的 `review/execution/report`
|
||
- 历史 / 证据:`docs/agent-specs/_archive/`、close-out reports
|
||
- **检索入口** = `docs/agent-specs/_index.md`(活地图)+ git grep + frontmatter
|
||
- **界外**:Claude auto-memory(`~/.claude/projects/.../memory/`,引擎托管 · 在仓外 · 每会话私有)—— 仅是个人加速器;**仓库才是权威源**,任何可复用的东西必须蒸馏回 `.agents/` 才算数。
|
||
- **死库**:`docs/memorys/`(legacy,只读,不再增长;新的留痕去 `docs/brainstorms/` + `docs/plans/`)。
|
||
|
||
### 3.4 关键模块架构设计(引用 · 不在此展开)
|
||
|
||
各关键模块的简洁架构描述(**每模块 ≤50 字**:职责 + 架构组成 + 依赖)集中在单一 SoT [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md),本入口只给指针、不重复内容:
|
||
|
||
- **§5 = 13 个后端业务模块速查**:studio · project · aigc · runtime · feed · telemetry · pay · trade · community · ip · compliance · biz · ad;
|
||
- 配 **§3 分层架构** · **§4 三仓与模块归属** · **§6 模块依赖图** · **§8 Game SDK 分层**。
|
||
- **更深一层**的子系统现行架构(生成主线 / 引擎与运行时 / 渠道发行 / studio 前端 / 变现与单位经济 等)→ `docs/architecture/` 6 域树(2026-06-20 改根),导航见 [`docs/architecture/README.md`](docs/architecture/README.md);生成引擎子树 🚧 演进中。
|
||
|
||
---
|
||
|
||
## 4. 任何任务开工前的必读顺序
|
||
|
||
**设计文档已于 2026-06-20 域化重构**:策展层设计 SoT 根 = [`docs/architecture/README.md`](docs/architecture/README.md)(总索引,6 域 4 级人读散文树)。首次 onboarding 或架构级任务从它进;日常开发优先读 [`.agents/knowledge/`](.agents/knowledge/) 蒸馏版。
|
||
|
||
| 顺序 | 文档 | 角色 |
|
||
|---|---|---|
|
||
| 1 | **[`docs/architecture/README.md`](docs/architecture/README.md)(设计文档总索引 · 唯一入口)** | 6 域设计树:产品(定位/需求/护城河)· 架构(分层/技术决策/13 模块 / **生成引擎 🚧 演进中**)· 前端 · 运营(变现/渠道/合规)· 后端 · 运维。**取代旧的系统概要设计×3 + Three-Doc Suite**(原档已归 `docs/architecture/_archive/`,决策史留档) |
|
||
| 2 | `docs/superpowers/specs/mvp-execution-spec-design.md` | MVP execution spec:10 人 × 3 周,contract-first(验收 = 55 个 P0 产品功能 / 工作量 ≈ 137 个技术项) |
|
||
|
||
> 提示:**蒸馏版位于 `.agents/knowledge/`,是日常默认入口**;设计细节进 6 域树按需下钻。
|
||
|
||
---
|
||
|
||
## 5. `.agents/` 目录导航
|
||
|
||
`.agents/` 是项目的"Agent 能力中枢",分为四类。维护规则见 [`.agents/README.md`](.agents/README.md)。
|
||
|
||
### knowledge/ —— 蒸馏后的事实与蓝图,回答"**它是什么**"
|
||
|
||
| 文件 | 一句话 |
|
||
|---|---|
|
||
| [`.agents/knowledge/product-and-architecture.md`](.agents/knowledge/product-and-architecture.md) | 产品定位、13 个模块及其依赖、三仓 / 三前端架构(蒸馏版) |
|
||
| [`.agents/knowledge/tech-decisions.md`](.agents/knowledge/tech-decisions.md) | 技术栈与关键选型理由(Huijing 框架 / 生成两条线 SAA+LittleJS 廉价线与 AgentScope+Phaser 富游戏线 / Cocos 退 3D·渠道导出轴 / 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) | 术语表(game feed / GameConfig / Manifest / quality score 等) |
|
||
|
||
### rules/ —— 硬约束,回答"**它必须怎样**"
|
||
|
||
| 文件 | 一句话 |
|
||
|---|---|
|
||
| [`.agents/rules/engineering-conventions.md`](.agents/rules/engineering-conventions.md) | 命名 / 分层 / API 路径 / 错误码 / commit / PR 规范 |
|
||
| [`.agents/rules/security-and-reliability.md`](.agents/rules/security-and-reliability.md) | 安全基线、幂等、超时与重试、合规与可靠性约束 |
|
||
|
||
### skills/ —— 可复用的 playbook,回答"**如何做某一类事**"
|
||
|
||
| 文件 | 一句话 |
|
||
|---|---|
|
||
| [`.agents/skills/add-business-module.md`](.agents/skills/add-business-module.md) | 新增一个 game-module 业务模块的标准步骤 |
|
||
| [`.agents/skills/add-game-template.md`](.agents/skills/add-game-template.md) | 新玩法模板上线配方(contract→prompt→runtime→backend→orchestrator→五级验收门) |
|
||
| [`.agents/skills/ai-generation-pipeline.md`](.agents/skills/ai-generation-pipeline.md) | AI 生成流水线(Dify + OpenGame + aigc 外壳)开发手册 |
|
||
| [`.agents/skills/cheap-model-game-generation.md`](.agents/skills/cheap-model-game-generation.md) | 便宜模型造游戏(W-G1):worker loop · 九门真玩 harness · design-agent 自产 gatespec · 成本 / 模型选择 · 5 个坑(HJ-GEN-001 已验证) |
|
||
| [`.agents/skills/saa-graph-orchestration.md`](.agents/skills/saa-graph-orchestration.md) | SAA 裸 StateGraph 生成编排:拓扑 / 加节点 / new-api(剥 /v1)/ checkpoint(含 saved_at 无 tiebreaker 的框架坑 + 显式 checkPointId 修法)/ 观测 / 最小依赖集 / dispatcher 契约 / 门(HJ-AGI-002 已验证) |
|
||
| [`.agents/skills/prompt-governance.md`](.agents/skills/prompt-governance.md) | Prompt 作为第 8 契约:Registry / 加载-注入 / eval 门 / HITL 治理 |
|
||
| [`.agents/skills/runtime-and-multichannel.md`](.agents/skills/runtime-and-multichannel.md) | Runtime 打包、沙箱、SDK 与多渠道导出手册 |
|
||
| [`.agents/skills/contract-first-development.md`](.agents/skills/contract-first-development.md) | Contract-first:对齐 API/DB/SDK/event 契约并解耦并行工作 |
|
||
| [`.agents/skills/wave-close-checklist.md`](.agents/skills/wave-close-checklist.md) | Wave 收口 8 步清单 —— 所有收口铁律指向的那份唯一可执行清单(第 8 步 = spec 退役/分层 + _index 维护) |
|
||
| [`.agents/skills/staging-ops.md`](.agents/skills/staging-ops.md) | Staging 运维配方:机器角色 / 代码同步 / 后端重部署 / 构建门 / smoke 门 |
|
||
| [`.agents/skills/ui-walkthrough-cdp.md`](.agents/skills/ui-walkthrough-cdp.md) | 在 mini-desktop 上经 CDP 做真 UI 走查(studio/admin)+ bridge 探针 |
|
||
| [`.agents/skills/game-e2e-cdp-harness.md`](.agents/skills/game-e2e-cdp-harness.md) | Canvas 游戏 e2e 证据 harness:编排形态 / driver 六规则 / ship 红线 / 四件套证据(T1b-α 已验证,W-G1 复用) |
|
||
| [`.agents/skills/doc-organizer.md`](.agents/skills/doc-organizer.md) | 文档整理助手（手动触发）：增量(上次清理→现在)·两阶段审批门——发起分析 Workflow→编清理计划→评审→创始人批准后才执行；三轴=过期档清理/核心设计档措辞对齐现行真相/主任务总账回填；配 `.agents/tools/doc-organizer.{sh,-analyze.mjs,-state.json}` |
|
||
|
||
### workflows/ —— 元流程,回答"**如何承接一项任务**"
|
||
|
||
| 文件 | 一句话 |
|
||
|---|---|
|
||
| [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md) | 完整 protocol:承接任务 → 分析 → 评审 → 执行 → 验证 → 蒸馏 |
|
||
| [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md) | MVP 10-Agent × 3 周执行编排 + 8 条复利效率策略 |
|
||
|
||
---
|
||
|
||
## 6. 工作协议(硬约束)
|
||
|
||
以下是浓缩条款;完整流程见 [`.agents/workflows/ai-development-protocol.md`](.agents/workflows/ai-development-protocol.md)。
|
||
|
||
1. **先读再动**:对任何有真实复杂度的任务,先读 [`.agents/knowledge/`](.agents/knowledge/) 及相关 `docs/`,对齐事实,再开工。
|
||
2. **复杂 / 高风险工作先评审**:跨模块、改变用户可见行为、或触及外部服务 / 支付 / 数据的任务,必须走 **评审版 → 两轮评审 → 再执行**;不要直接写代码。
|
||
3. **证据规则**:区分"已验证事实 / 推断 / 假设"。**没有验证证据,绝不宣称"完成 / 修好 / 通过 / 无问题"。** 任何可运行的东西(测试、构建、lint、smoke)都必须跑。
|
||
4. **最小改动**:只动与当前需求直接相关的代码,复用既有模式,不要随手重构无关的命名 / 目录 / 格式。
|
||
5. **中文注释**:所有代码都必须带完整的简体中文注释;外部交互、核心实现、错误路径都必须有可追溯的日志。
|
||
6. **Contract-first**:接口 / 数据结构变更要先改契约(`contracts/` 与 `-api` 包),再实现,并通知相关方。
|
||
7. **不留孤儿设计**:任何新功能、数据结构、API、领域模型或工作流,都必须连同其面向用户的入口、使用路径、失败模式与验收标准一并交付 —— 没有无入口的 API、没有不接产品流程的孤立能力、没有只是把一份 spec 硬凑到另一份上的拼接方案。
|
||
8. **plan 文档双(双边)评审门**(2026-06-18,创始人):**新建 brainstorm / plan 文档 —— 包括把新 units 折进一份既有活计划 —— 收口前必须过 Codex + Opus 双评审;若 Codex 不可用,回落到 Opus 单评。** 两者并行跑(`codex:codex-rescue` + 一次 Opus 对抗式文档评审),把设计前提喂进去以免有意决策被当成缺陷,在文档内修掉发现项,并把跨文档发现项列为收口 TODO。
|
||
9. **内网阶段:决策与密钥进项目文档,不进 env var**(2026-06-18,创始人):内网阶段,**所有决策、所有密钥/凭据都进项目文档**(内网 Tailscale 地址 / 密钥 / token 明确允许入仓)。密钥 → [`docs/内网凭据与端点.md`](docs/内网凭据与端点.md)(single source of truth —— `NEWAPI_KEY` / 端点 / 机器都在那)。**需要 key?读那份文档 —— 不要再问创始人,也不要依赖环境变量。** 决策 → 相应的 plan / 活档,永不只留在聊天里。
|
||
10. **文档治理强制门 —— 把规则编译成机器门(规则必须编译成机器门,否则等于没有)**(2026-06-20,创始人文档治理工作):在无状态 agent 系统里,每一条文档治理规则(§7;[engineering-conventions §10](.agents/rules/engineering-conventions.md))只作为散文存在就毫无价值 —— 一个无状态、单会话的 agent 不会去"自我执行"它。规则必须被编译成机器门,在 wave-close 与 pre-commit 时运行,并 **在违规时红线拦截**:**① 品牌不变量门(brand-invariant)** —— `rg` 在活层里搜退役名 `造梦AI` 返回零(白名单:`docs/ip` 法律备案、`_archive`、带日期的留痕文档);**② canonical 唯一性门(canonical-uniqueness)** —— 每个 `topic` 至多一份文档标记为 canonical;第二份即红线(杀掉 doc-sprawl / 影子 SoT);**③ doc↔code 兑现门(fulfillment)** —— 一项基石设计的关键产品约束,要携带真正会运行的、机器可校验的断言(例如:生成产物必须是 `src/` 多文件项目;逻辑不得只以 JSON 字符串 / `new Function` blob 的形式存在)—— 设计声称 X,代码就必须可验证地兑现 X;**④ 入口卫生门(entry-hygiene)** —— AGENTS.md 只承载项目事实:扫描禁入 `git clone` / 全局工具安装 / 个人绝对路径(`~/.claude`)/ 硬编码端口。门脚本 + 白名单见 [engineering-conventions §10](.agents/rules/engineering-conventions.md)。
|
||
11. **横切一致性主人 + AGENTS.md 自审(整体一致性必须有一个有状态的主人)**(2026-06-20,创始人文档治理工作):跨文档 / 跨任务 / 跨时间的一致性 —— SoT 收敛、品牌统一、设计↔代码兑现,以及 AGENTS.md 自身的新鲜度 —— 不得继续无主地压在"主 agent"(一个无状态、用完即弃的主体)身上,因为 *人人无主即无人为主*,整体随后会被局部最优的 agent 悄悄侵蚀。要显式指派:**横切一致性主人 = 创始人 + 6c6g 文档/设计线**(一个有状态的主体),负责机器门做不出的灰色地带判断(哪份文档过期了、两份冲突文档哪份胜出、一个补丁是否其实是架构信号)。并且 **AGENTS.md 自审** —— 入口文件也会过期,而无人看守的根最危险(改名十天后它的标题仍写着"造梦AI"):任何改名 / 子系统增删 / 核心决策被推翻时,**同一个 commit** 必须重审 AGENTS.md;wave-close 门扫描它(品牌残留、死链、canonical 对账、入口卫生);主人定期做一次全量复审。
|
||
12. **落档文档 = 资深工程师写的散文,不是 AI 产出**(2026-06-21,创始人):架构 / 设计 / 分析 / 评审 / 方案文档要清晰表达、逻辑连续,必要处配直白图表,写成流畅的人读散文。**禁三样**:**① 元叙述** —— 不写讲述文档自身或写作过程的话("本文讲什么 / 下面介绍 / 这里要诚实交代 / 前面讲过 / 后面会讲 / 一句话收束"),直接陈述内容,逻辑靠内容自己往前走、不靠连接词宣告;**② AI 造词与黑话堆砌** —— 不自造唬人的新词、不堆缩写行话(项目既有术语如 SAA / 九门 / O2 可用,首次出现讲清);**③ 套话空强调** —— 去掉"至关重要 / 本质上 / 归根结底 / 值得注意的是"这类填充。口头汇报仍紧凑,但紧凑 ≠ 黑话。**派子代理 / Workflow 写文档,必须把本标准连同正反例一起传下去** —— 实测只传"写散文"不够,输出会退回 AI 味(2026-06-21 控制面 v2 即栽在此)。
|
||
|
||
---
|
||
|
||
## 7. 知识累积机制(同样是硬约束)
|
||
|
||
`.agents/` 的目的,是让团队在长期开发中 **复利式累积能力**,持续抬高 AI 驱动开发的 **能力、准确度与稳定性**。因此:
|
||
|
||
- **每完成一项有价值的任务,你都必须把可复用的产出写回对应的 `.agents/` 目录:**
|
||
- 新事实 / 蓝图知识 → `knowledge/`
|
||
- 新硬约束 / 踩坑红线 → `rules/`
|
||
- 新的可复用操作 playbook → `skills/`
|
||
- 流程级改进 → `workflows/`
|
||
- **新增前先查重**:优先更新既有文件而非新建;立刻修正或删除过时内容。
|
||
- **改动 `.agents/` 时,同步更新 [`.agents/README.md`](.agents/README.md) 里的索引与交叉链接**,以保持导航一致。
|
||
- 所有内容保持 **简体中文**、单一主题、简洁、易于快速检索。
|
||
|
||
> 没有蒸馏的任务是一次性消耗;有了蒸馏,下一个类似任务才能更快、更准地在既有成果上接着干。
|
||
|
||
---
|
||
|
||
## 8. 效率原则(复利)
|
||
|
||
AI 驱动开发应当"**越做越快**"—— 把每一份产出蒸馏成可复用资产,让效率随工作推进而复利累积。8 条核心策略(见 [`.agents/workflows/mvp-execution-orchestration.md`](.agents/workflows/mvp-execution-orchestration.md)):
|
||
|
||
1. **黄金模板先行**:先把一个模块打磨到位,再克隆它的骨架到其余模块。
|
||
2. **Contract-first**:在任何并行工作之前先锁定契约(API/DB/SDK/event)。
|
||
3. **复用优先于重建(三级次序)**:写代码前,按顺序搜索 —— ① 仓内(`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. **验证门前置**:TDD + 门 + 完成前验证,尽早抓出错误、防止返工(返工是头号效率杀手)。
|
||
5. **并行边界 = 模块边界**:agent 之间零共享状态、worktree 隔离、只经契约交互。
|
||
6. **`.agents` 复利蒸馏**:每次交付都把学到的东西写回(见 §7)。
|
||
7. **缓存昂贵步骤**:Prompt hash 命中就跳过 LLM;缓存构建 / 产物。
|
||
8. **可复现编排**:把 fan-out + verify 冻结进 Workflow 脚本。
|
||
|
||
---
|
||
|
||
## 9. gstack 工具集(全局 · 仅指针)
|
||
|
||
gstack 是一套 **按开发者机器安装的全局工具**(browse / review / QA / deploy / docs)。它 **不属于本项目**:其安装与完整用法存在于每位开发者的全局环境配置里(全局 `CLAUDE.md`),**不在本项目入口**。项目约定仅此一条:**所有网页浏览 / 评审 / QA 都经由那个唯一的 `/gstack` 入口走**,前提是机器已装好它。
|
||
|
||
> **入口卫生规则:** 这份顶层 SoT 入口只承载 **项目事实** —— 绝不放按机器的 setup、安装命令或个人绝对路径。那些存在于开发者的全局配置里,不在这里。(这条规则本身由文档治理工作中引入的品牌/入口卫生门强制执行。)
|