Agentaily Docs

外观

CLAUDE.md — Agentaily Design System(组件库本体) ​

这是上游组件库 @agentaily/design-system(单色亮色优先的 React 组件库 + Storybook)。 本文是入口与约定速查;细节各有专档,别在这里重复。

位置(2026-06-17 起): 本组件库已并入 agentaily 大 monorepo(pnpm + Turbo),作为工作区包 design-system/, 由 apps/web 等以 "workspace:*" 直接依赖、改了即生效(pnpm --filter @agentaily/design-system dev 监听重建 dist)。 npm 发布已停、无 lefthook / changesets;monorepo 是唯一真相源。外部仓仍吃 npm 上最后发布的版本。

文档地图 ​

  • 品牌 / 设计规范全文 → DESIGN.md
  • 能力地图(已完成 / 进行中 / 待办) → ROADMAP.md
  • 运维手册(构建产物 / 故障排查) → OPERATIONS.md
  • 测试分层 / 选型 / 护栏 → TESTING.md(逻辑组件的 vitest 单测 gate;测试落 tests/,别动镜像组件)
  • 消费者使用指南(给下游用的 skill) → skill/SKILL.md

关键约定(改这个仓库前必读) ​

2026-06-19:Claude Design 工作流(claude.ai/design → handoff → design-sync)已退役。 组件现在直接在本仓维护 —— 不再从 handoff 镜像、不再用 design-sync 三路合并。

  • 组件结构:每个组件 ship .jsx + .d.ts(props 契约)+ .prompt.md(用法)+ .stories.jsx。 .d.ts 与 DESIGN.md 不被 prettier 触碰。
  • 改 / 加组件直接在本仓写(基于既有约定:token-only、双主题)。
  • src/index.js 是自动生成的(pnpm --filter @agentaily/design-system gen:barrel),别手改;增删组件后手动跑它重生成 barrel(monorepo 无 lefthook 自动钩子)。
  • 验证改动(根目录):pnpm test(DS 走 jsdom project)+ pnpm --filter @agentaily/design-system build +(可选)pnpm --filter @agentaily/design-system build-storybook。改完 apps/web 即时吃到新 dist(或用 turbo run build 全量按序构建)。
  • 组件计数有两个口径:barrel 模块数(= .jsx 文件数,见 package.json / README / ROADMAP / skill) 与 DESIGN.md 的「component exports」数(含 hook / helper 等子导出)。增删组件时两处都要同步。
  • 改公开能力(组件 / 导出 / prop / 默认值)时,同一次改动里更新消费文档:对应 .prompt.md、 DESIGN.md、README.md、skill/SKILL.md、ROADMAP.md、组件计数(同一次改动里)。

Sub agents(项目级分工 · 镜像库裁剪版) ​

这个仓库有项目级 sub agents,见 .claude/agents/README.md。注意:它仍不是 form-design 那种双循环 TDD 产品 —— 没有 src/core 逻辑层、没有 SPEC/Gherkin features/、没有 integration/e2e 套件。组件直接在本仓维护,仓库自写 .stories.jsx 和 tests/ 里的单测。 本仓长出了第一个有逻辑的原语 —— <Markdown>(parser + XSS 净化 + 流式容错), 所以正如 agents/README 早写好的预言,vitest 单测 gate + 重引 implementer + TESTING.md 都已落地。

2026-06-19:Claude Design 工作流已退役。 原 design-syncer 角色(用 design-sync 落地 handoff)随之退役 —— 组件改动现由 implementer / worker 直接在本仓写。

Agent干什么
implementer组件 / 逻辑原语(parser/sanitizer/有状态 hook,如 <Markdown>)的实现 + 单测内环:红→绿→重构,写组件 + tests/,写 stories + 同步计数/文档/changeset
reviewer独立只读对抗 review:四件套齐不齐、双主题、token-only、barrel 没被手改、单测质量 + 安全契约
release-engChangesets 自动发版 · lefthook · Storybook→Pages · 破坏性变更通知下游(见 RELEASE.md)
pr-analystPR triage / 路由(只读)

仍裁掉的:spec-architect(无 SPEC/features)、outer-tester(有 unit 但无 integration/e2e 套件,没 features/ 可 realize)、designer(本仓就是组件库,不消费别的 DS)。理由详见 agents/README「Why this roster」。别往这个仓库 重新塞这些角色——它们没东西可 own。验证靠 npm test(逻辑组件单测)+ npm run build:lib && npm run build-storybook

  • Storybook 双主题肉眼看(分层与护栏见 TESTING.md)。

自主运作约定(就绪 + 双轮询) ​

被 fleet 起成常驻终端后,读完本 CLAUDE.md + .claude/agents/README.md 即就绪,开始双轮询:

  • 自己仓的 PR(任务工单):gh pr list --label autopilot --draft → pr-analyst 分析 → 按性质路由 (组件 / 逻辑实现 → implementer · stories/docs → implementer 轻量 · 发版/CI → release-eng · 破坏性通知 → release-eng · 设计方向不明 → 叫人)→ worktree 隔离 + 落地 + 自测(npm test + build:lib + build-storybook)+ push 到 PR 分支 + 等 CI。
  • 组件直接在本仓写(Claude Design 工作流已退役,不再有上游设计项目轮询)。本仓是发布端而非消费端,不轮询自身的 NPM 发版;下游 form-design 那边轮询本包的新版本。

命门(不自主,叫人):合并 PR · 设计方向拍板 · 触发不可逆发布 (合 Version PR / 发 npm)· 给下游开破坏性迁移 PR · 要凭证 / 点 GUI。push 到自己 draft PR 分支可自主 (仍要人 review + 合)。轮询用 ScheduleWakeup 控节奏(空闲拉长省钱)。