子 agent(Subagents)

agentaily 的项目级子 agent。每个职责单一、工具最小权限,经持久 artifacts 沟通 —— features/ 是每个人据以工作的契约。本项目自洽:下面的方法论 + TESTING.md(测试策略 / 分层 / 护栏)就是这些 agent 的共享真相 —— 无需外部 skill。

角色表

每个角色的完整契约(拥有什么路径、用什么框架、领域概念、安全检查点)在它各自的 .claude/agents/<name>.md 里;下表只是一眼概览。

Agent	拥有(概览)	不碰
spec-architect	features/(Gherkin 行为契约)+ 跨包 strict-TS 契约层(aml/src/types.ts · backend · db · presets · apps/web/src/core/*)+ 真相源文档(REFACTOR/SPEC/ARCHITECTURE/ROADMAP)同步	实现体、测试、CI
implementer	内环:契约层实现体 + app UI(消费 @agentaily/design-system)+ 它们的 vitest 单测(红→绿→重构,同一只手)	写 features、外环测试、CI
outer-tester	外环:@amiceli/vitest-cucumber + Testing Library(jsdom)集成测试,realize features/ 场景(e2e 当前未引入)	产品 / 源码、写 features
reviewer	独立、只读、对抗 review(正确性 / 契约 / 测试质量 / 安全)	改任何文件
release-eng	GitHub Actions CI(typecheck→test→build)+ Cloudflare Pages/Workers/D1 CD + Turbo + Prettier	产品代码、features、测试
designer	UI 直接基于 @agentaily/design-system 在代码里实现 + DESIGN.md	产品逻辑、测试、CI

流程(双环 TDD/BDD + worktree/PR 驱动)

原则(五条铁律 —— 本项目的方法论真相)

• 契约优先:经 artifacts(features/、类型、结构化报告)交接,而非散文。
• 独立验证:reviewer ≠ implementer;reviewer 只读且对抗。
• 别拆分内环:同一个 agent(implementer)写一个单元的失败测试和它的代码。
• 最小权限:工具把边界编码进去(reviewer 没有 Write)。
• 并行需要隔离 → worktree + PR:让并发的 agent 在各自的 git worktree + 分支里跑(经 spawn-terminal),然后开一个 PR。物理隔离取代任何共享工作树的协调 —— 文件域不能重叠。
• 持久记忆:每个 agent 带 memory: project + 一个 # Persistent Agent Memory 块 —— 学到的东西累积进 .claude/agent-memory/<agent>/(每 agent、项目作用域、版本控制 & 团队共享),并跨对话留存。

经 Agent 工具调用(subagent_type: <name>),或为每个 agent 起一个独立终端(spawn-terminal)做并行的 worktree/PR 工作。主循环始终是 orchestrator:它按 feature 拆分、路由、并调和冲突。

编排策略(老板定 —— 复杂走全套,小改直接做)

主循环(orchestrator / 主会话)按改动复杂度选档,自己判断:

• 复杂功能 → 走全套:spec-architect(写 features/ 契约 + 契约层 stub)→ implementer(内环红→绿→重构)→ outer-tester(外环验收,realize 场景)→ reviewer(独立对抗,ship/fix-first)→ release-eng(发版);并发的角色各开 git worktree + PR(铁律 5)。reviewer 判 fix-first → 回 implementer 修 → 再 review,直到 ship。
• 简单小改 → orchestrator / 主会话直接做:文案、一行修复、配置微调、纯文档这类,不必起全套 —— 主会话自己小改、自己把 pnpm typecheck && pnpm test && pnpm build 跑绿即可,别为了仪式感拉满五个角色。
• 判据:影响面 / 风险 / 是否碰契约或公开能力 / 是否需要独立验收。拿不准就往「全套」靠,尤其碰安全命门(沙箱 / scoped 数据 / 鉴权 / BYOK)、契约层、或跨包改动时。

行为契约 features/(放哪 + 种子)

• 约定:Gherkin .feature 放在它所描述的那个包根的 features/ 下(monorepo 惯例)—— 如 apps/web/features/、apps/website/features/(官网的 switch-locale.feature 是已 realize 的活例)。外环测试用 loadFeature 以相对测试文件的绝对路径引它(见 TESTING.md 的坑)。
• 种子(本次装配带入,apps/web/features/):build-app.feature(用户在 /build 聊天造 app → 右侧实时预览)、market-fork.feature(fork 一个公开 app → 得到我自己的副本)。两条都是已落地能力的行为契约,但尚未 realize 成外环测试 —— 是给 outer-tester 的 handoff(写集成测试时需先给 apps/web 配 jsdom vitest.config.js 并入根 projects,见 TESTING.md)。