CLAUDE.md —— agentaily monorepo(项目级指引)
「聊天 × 万物」:你跟一个 chat Agent 聊,它生成一个【应用】= aml(声明式后端数据模型 → 框架自动建 D1 表 + 自描述数据接口)+ 一组前端文件(零构建 VFS:index.html 入口 + 按需 css/js)+ 描述 + 预览;发布到市场(核心价值),别人可浏览 / fork。当前架构收敛蓝图见 REFACTOR.md。
- 真相源:
REFACTOR.md(架构收敛蓝图,当前)·SPEC.md(契约)·ARCHITECTURE.md(架构,部分仍描述旧模型、以其 banner 为准)·ROADMAP.md(能力地图 + 进度)。干活前先对它们。 - 栈:pnpm + Turbo monorepo;
apps/web=主 SPA(/= ChatApp 聊天造 app + 会话绑定预览工作台 + 市场弹窗;基于 DSChatApp壳)+ Pages Functions(CF Pages 上线 https://agentaily.pages.dev),apps/publish=UGC 独立源沙箱(/a/:appId跑发布的 app),apps/website=官网,design-system/backend/db/llm/agent/agent-store/presets(市场)等工作区包(verticals/*+ studio 协议已删,M7;独立apps/market已收为 web 内弹窗并删)。 - UI 分层原则(老板定,做 UI 前必读):组件 + 交互的设计与开发,全部在
@agentaily/design-system(Storybook)里完成 —— 包括应用层级组件(ChatApp/ 预览工作台 / 市场弹窗 等整块交互;DS 组件层级一路覆盖到应用层,在storybook.agentaily.com独立打磨/评审)。apps/web等业务前端只做「组合调用 + 接数据」,是薄层,不写组件/交互逻辑。 接到 UI 活 → 先在 DS 建组件(四件套 + stories + 单测)→ app 再消费组合。信号:app 里出现成块组件/交互逻辑 = 该下沉到 DS。 详见记忆ui-built-in-design-system-app-only-composes。 - 验证:根目录
pnpm test·pnpm typecheck·pnpm build(=turbo run build;零构建 VFS 沙箱直跑,无 studio 汇入步)。
🌳 推进模型:git worktree + PR(动手前必读)
每个 agent / 终端在自己的 git worktree 里干活、提 PR 合并 —— 不再多 session 共用同一个工作树。 物理隔离,各干各的,不互相踩。
- 从
main开自己的 worktree(<repo>/.claude/worktrees/<slug>,被 .gitignore 掉)+ 分支,在里面改、提交到自己的分支,然后 开 PR → 合并回main。起独立终端 + worktree 用全局 skillspawn-terminal。 - 本地该提交就提交(commit 是常态、别把工作攒在未提交态);集成走 PR / merge。
- 窄提交:
git add <你明确的路径>,别git add -A把无关东西扫进来;git commit前git diff --cached --name-only自检。 - 绝不 force-push;被拒(non-fast-forward)→
git pull --rebase再推。 - 有自动部署(CD:合并 / push
main→ 部署 agentaily + 官网)。进main的每个提交都要自洽可构建,别让 CD 红。
旧的「多 session 共用同一个工作树 +
COLLAB.md协作板 +session-collabskill」模型已退役 —— worktree 物理隔离后不需要协作板。
🤝 双循环 TDD/BDD + sub-agent 角色(动手前对)
本仓装了一套项目级 sub-agent(.claude/agents/),把「让 AI 写代码」组织成职责分明、靠 artifacts 交接、互相独立验证的小团队 —— BDD 外环(features/*.feature 行为契约 → outer-tester 集成验收)+ TDD 内环(implementer 红→绿→重构)+ 独立 reviewer + spec-architect / designer / release-eng。角色边界 / 交接协议 / 五条铁律 / 编排策略(老板定:复杂功能走全套、简单小改 orchestrator 直接做)都在 .claude/agents/README.md;测试分层 / 框架 / 护栏在 TESTING.md。
- 怎么用:主会话是 orchestrator,按 feature 拆活 → 路由给角色(
Agent工具subagent_type: <name>,或派spawn-terminal终端跑 worktree/PR)。每个角色自带项目作用域持久记忆(.claude/agent-memory/<agent>/,进版本控制)。 - 行为契约
features/:放在它所描述的那个包根(如apps/web/features/、apps/website/features/)。 - 项目级 agent 优先于全局同名 agent;这套配置自洽,不依赖任何全局 skill。
📚 根文档索引 + 维护纪律(动手前对、推进中维护)
仓库根的这组 Markdown 是「这个项目是什么、怎么干、怎么上线、当下在做什么」的真相源体系。干活前先对相关的那几份;推进中你就是它们的维护者 —— 见文末「维护纪律」。
| 文档 | 是什么 | 何时读 |
|---|---|---|
README.md | 项目简介 + 仓库地图 | 第一次了解项目 |
ARCHITECTURE.md | 架构设计与理由(Agent ⟷ Studio 协议) | 加包 / 加垂直 / 改结构前 |
SPEC.md | 精确契约(协议 / 数据形状 / op 语义 / 不变量) | 碰协议 / 数据形状前 |
ROADMAP.md | 能力地图 + 当前进度 | 看「能做什么 / 接下来做什么」 |
REFACTOR.md | 架构收敛重构蓝图 + 工单(M0–M8) —— 市场为核心 · AML+Cloudflare 为基建 | 当前重构真相源;碰收敛态架构 / 认领重构工单前 |
DEVELOPMENT.md | 本地开发指南(环境 / 端口 / 后端 D1 / 构建) | 在本地跑 / 改 / 验证时 |
TESTING.md | 测试分层 / 框架选型 / 护栏 | 写测试前 |
DESIGN.md | 设计规范入口(指向 skill + 上游 DS) | 做 / 改 UI 前 |
DOMAINS.md | 域名 / DNS 方案(官网 / 应用 / 发布子域) | 碰域名 / 部署目标前 |
OPERATIONS.md | 运维手册 —— 线上资产 / secret / CD 机制 / 冒烟 / 回滚 / 数据 / 应急 | 跑住线上 / 出事 / 改 secret / 跑迁移前 |
RELEASE.md | 发版手册 —— 一处改动怎么走到生产 / 盯 CI 到绿 / 版本策略 / npm 发版(未来) | push main / 上线前 |
CLAUDE.md | 项目级 Agent 指引(本文) | 每个 session 自动加载 |
.claude/agents/README.md | 双循环 TDD/BDD + sub-agent 角色总览 + 编排策略 | 拆活 / 路由给角色 / 起 worktree 干活前 |
维护纪律(你推进工作时,负责让它们不漂移)
这些根文档不是写完就锁死的死文档 —— 谁的改动碰到了某份文档覆盖的现实,谁就在同一次改动里把它更新到位。 把「文档声称系统有 X」与「系统实际是 X」之间的漂移,当成和代码 bug 一样要修的 bug(全局准则「让面向消费者的文档与代码保持同步」的项目落地)。
⏱️ 会话「开始」轻量对齐、「结束」防漂移全扫 —— 主会话和 worker 子终端都适用(两端不对称)。
- 开工前(会话 / 任务开始)= 对齐当前状态,不必全读:读本索引表 + 当前真相源(
REFACTOR.md/ROADMAP.md)+ 任务相关那几份(按上表「何时读」);别基于过时认知开干。worker 子终端读提示词点到的 + 与本刀相关的那几份即可。- 收尾时(会话结束 / 一段实质工作完成 / worker 写
DONE.md前)= 防漂移全扫:对着根目录所有*.md的清单逐份自问「我这次改动碰到它覆盖的现实没?碰了就按下面分类更新」—— 是对照改动的扫描、不是重读全文。漏检 = 留 bug。
- 新增 / 改变一个公开能力(组件 / 导出 API / prop / 配置 / 端点)→ 同步
README.md/ARCHITECTURE.md/SPEC.md/ 各组件用法 +ROADMAP.md(标进度)。 - 改了构建 / 测试 / 本地开发方式 → 同步
DEVELOPMENT.md/TESTING.md。 - 改了线上资产 / secret / CD 行为 / 迁移 / 回滚 / 域名 → 同步
OPERATIONS.md(必要时DOMAINS.md)。 - 改了发版方式 / CI 门禁 / 版本策略 / 接上 npm 自动发版 → 同步
RELEASE.md。 - ship 或开启一个能力 → 同次更新
ROADMAP.md(能力粒度);细节链到SPEC.md/ PR,不复述。 - 改这些根文档:在自己的 worktree 里改、窄提交、走 PR 合并(见上「推进模型:git worktree + PR」)。