elephant-build

Elephant Build 🐘

大象从不犹豫。它看准前进方向，收集所需的一切，然后以势不可挡的势头开始构建。一份文件接着一份文件，一个系统接着一个系统，大象创造出其他人认为过于复杂而不敢尝试的成果。当一项功能跨越多个边界——从前端到后端、从 API 到数据库、从配置到部署——大象会一路推进，直至完成。

何时启用

• 用户要求“实现此功能”或“构建此系统”
• 用户要求创建需要涉及多个文件的内容
• 用户调用 /elephant-build 或提到 elephant/building
• 功能涉及前端、后端和数据库
• 新增 API 端点并集成客户端
• 数据库迁移并修改代码
• 复杂的 UI 流程需要状态管理
• 任何需要跨模块协调修改的工作

搭配使用： 先用 bloodhound-scout 进行探索，再用 beaver-build 进行测试

---

构建流程

TRUMPET → GATHER → BUILD → TEST → CELEBRATE
    ↓        ↓        ↲        ↓         ↓
Declare  Collect   Construct Validate   Complete
Vision   Materials  Power    Strength   Triumph

阶段 1：TRUMPET

大象举起长鼻，吹响开始的号角……

明确声明我们要构建什么，并完整界定范围。

• 用一句话说明：此功能为用户实现什么？
• 定义范围边界——明确哪些内容属于范围，哪些明确不属于
• 创建文件清单：新文件、修改的文件和配置变更
• 确定构建顺序：架构 → 服务 → API → UI → 集成 → 测试

参考： 加载 references/file-patterns.md，了解 SvelteKit 文件模式、组件结构和 API 路由约定

输出： 清晰的愿景、范围边界、文件清单和构建顺序

---

阶段 2：GATHER

大象收集石块和树枝，为地基做好准备……

在开始构建前，收集所需的一切。

• 检查依赖项——确认所需软件包已安装，并安装缺少的软件包
• 使用 gf --agent usage "ServiceName" 和 gf --agent func "functionName" 研究现有模式
• 检查类似实现，在采用不同做法前了解现有约定
• 在 .env.local 和 .env.example 中设置环境变量

输出： 所需材料全部备齐，依赖项就绪，模式清晰

---

阶段 3：BUILD

大象精准地放置每一块石头，构建经久耐用的成果……

按顺序逐个文件构建功能。

• 首先构建数据库和基础部分（架构、类型、常量）
• 其次构建后端服务（业务逻辑、数据访问）
• 第三构建 API 层（端点、验证、错误处理）
• 第四构建前端组件（UI、状态管理）
• 最后进行集成（将所有部分连接起来）
• 一次处理一个文件——完成后再继续下一个
• 遵循现有模式——保持代码库风格一致
• 在每条错误处理路径中使用 Signpost 错误代码
• 验证所有输入；全程添加 TypeScript 类型

参考： 加载 references/build-checklist.md，了解多文件构建检查清单、集成连接步骤和数据库架构模式

参考： 加载 references/signpost-errors.md，了解 Signpost 错误代码、不同场景下应使用的辅助函数，以及 toast 反馈模式

输出： 在所有必需文件中完成实现

---

Phase 4：TEST

大象逐一测试每块石头，确保结构稳固……

强制要求：提交前验证构建结果。大象不会交付不稳固的结构。

pnpm install
gw ci --affected --fail-fast --diagnose

如果验证失败：阅读诊断信息，修复错误，然后重新运行验证。重复此过程，直到结构稳固。

CI 通过后，进行手动验证：

• 端到端的正常流程可正常运行
• 错误状态得到妥善处理
• 加载状态正常
• 移动端布局正确
• 键盘导航和无障碍功能通过检查

组件审查关卡（适用于 UI 功能）：

如果大象构建或修改了 UI 组件，它会先使用 Showroom 单独审查每个组件，再进行页面级 Glimpse。Showroom 会在组件层面发现设计令牌违规、间距偏离网格、缺少焦点样式和硬编码颜色等问题。带强调色的表面必须使用 var(--grove-accent-*) 令牌（而非硬编码的绿色十六进制值）——提交前钩子会强制执行这一要求。

# For each component built or modified:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

# For brand new components, scaffold a fixture first:
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte --scaffold
# Then run the audit (auto-reads the fixture for scenarios)
uv run --project tools/glimpse glimpse showroom \
  libs/engine/src/lib/ui/components/[path-to-component].svelte

这是必需的关卡。 必须解决所有合规性违规，才能继续进行页面级验证。大象不会交付未经审查的组件。

视觉验证（适用于 UI 功能）：

如果大象构建了 UI，它会先检查结果，再确认结构稳固：

# Prerequisite: seed the database if not already done
uv run --project tools/glimpse glimpse seed --yes

# Capture the page to see what was actually built
# Local routing uses ?subdomain= for tenant isolation; --auto starts the dev server
uv run --project tools/glimpse glimpse capture \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --season autumn --theme dark --logs --auto

# Walk through the feature visually
uv run --project tools/glimpse glimpse browse \
  "http://localhost:5173/[page]?subdomain=midnight-bloom" \
  --do "interact with the new feature" --screenshot-each --logs --auto

检查截图。如果显示效果不对，就修复并重新截图。大象不会交付未经检查的结构。

输出： 所有测试均通过，视觉和手动验证已完成，边缘情况均已处理

---

Phase 5：CELEBRATE

大象高举象鼻庆祝，构建大功告成……

交付并编写文档。

git add -A && git commit -m "feat(component): brief description of feature"

编写完成摘要：创建的文件、修改的文件、配置变更、添加的测试以及验证状态。

输出： 功能已完成、已测试、已编写文档，可用于生产环境

---

参考资料路由表

阶段	参考资料	加载时机
TRUMPET	references/file-patterns.md	规划新的 SvelteKit 文件时
BUILD	references/build-checklist.md	跟踪多文件构建进度时
BUILD	references/signpost-errors.md	实现错误处理时

---

大象规则

保持进度

继续向前推进。不要在一个文件上耗费数小时。如果受阻，就添加 TODO，然后继续。大象不会停下。

完整性

构建完整的功能。半成品功能无法帮助用户。如果范围太大，就缩小范围——但要完成已开始的工作。

质量

一次就把事情做好。测试、错误处理、类型——这些不是额外工作，而是构建的一部分。

沟通

使用建筑隐喻：

• “吹响号角……”（阐明愿景）
• “收集材料……”（准备工作）
• “逐块放置石头……”（构建）
• “测试结构……”（验证）
• “构建完成！”（庆祝）

---

反模式

大象绝不会：

• 未理解范围就开始构建
• 因为“以后再加”而跳过测试
• 留下 TODO 注释而不完成工作
• 破坏现有功能
• 忽略正常流程之外的错误情况
• 不求甚解地复制粘贴

---

构建示例

用户：“为博客文章添加评论系统”

Elephant 流程：

1. 🐘 TRUMPET — “用户可以在博客文章下发表评论并进行串回复。范围：基本 CRUD、串回复、审核。不包括：实时更新、表情回应。”

2. 🐘 GATHER — “需要：评论表架构、评论服务、API 端点、Comment 组件、递归显示逻辑。检查：现有身份验证模式、文章的工作方式。”

3. 🐘 BUILD — “架构 → 服务（CRUD + 串回复）→ API 端点 → CommentList/CommentForm 组件 → 接入文章页面 → 添加审核 UI”

4. 🐘 TEST — “服务单元测试、API 集成测试、UI 组件测试、手动测试串回复深度限制”

5. 🐘 CELEBRATE — “新建 8 个文件，修改 3 个文件，45 项测试通过，已记录审核工作流”

---

与其他技能集成

构建前： bloodhound-scout — 探索现有模式；eagle-architect — 用于复杂的系统设计；swan-design — 需要详细规范时使用

构建期间： chameleon-adapt — 用于 UI 润色；beaver-build — 用于测试策略

构建后： raccoon-audit — 安全审查；fox-optimize — 发现性能问题时使用；deer-sense — 无障碍审查

---

独自看来不可能之事，借助大象的势头终将成为必然。 🐘