快速开始
2.1 安装
# 全局安装
npm install -g @mindfoldhq/trellis@latest
# 在项目目录初始化
cd your-project
操作系统要求: Mac、Linux、Windows 完整支持。脚本已全部迁移为 Python，跨平台兼容。
- Claude Code
- Cursor
- Codex
- OpenCode
- Kilo
- Kiro
trellis init -u your-name
.claude/ 目录（commands、agents、hooks）。trellis init -u your-name
.cursor/commands/ 目录。trellis init --codex -u your-name
AGENTS.md 和 .agents/skills/。trellis init --opencode -u your-name
.agents/skills/。支持 session hook 自动注入上下文。trellis init --kilo -u your-name
.kilocode/ 目录（workflows、rules、skills）。trellis init --kiro -u your-name
.kiro/ 目录（steering、hooks、prompts）。your-name 会成为你的开发者身份标识，并创建个人工作区 .trellis/workspace/your-name/。
2.2 平台配置
trellis init 会自动检测并配置已安装的平台：
| 平台 | 配置目录 | 命令格式 |
|---|---|---|
| Claude Code | .claude/commands/trellis/, .claude/agents/, .claude/hooks/ | /start |
| Cursor | .cursor/commands/*.md | /start |
| Codex | AGENTS.md, .agents/skills/ | $start |
| OpenCode | .agents/skills/ | /start |
| Kilo | .kilocode/workflows/, .kilocode/rules/, .kilocode/skills/ | /start.md |
| Kiro | .kiro/steering/, .kiro/hooks/, .kiro/prompts/ | @start |
平台能力对比
| 能力 | Claude Code | Cursor | Codex | OpenCode | Kilo | Kiro |
|---|---|---|---|---|---|---|
| 会话自动注入 | ✅ Hook | ❌ 手动 /start | ⚡ AGENTS.md | ✅ Hook | ⚡ rules/ + launchConfig | ⚡ steering/ |
| 子 Agent 规范注入 | ✅ PreToolUse Hook | ❌ | ❌ | ❌ | ⚡ Orchestrator Mode | ⚡ Custom Agents |
| Ralph Loop 质量门 | ✅ SubagentStop Hook | ❌ | ❌ | ❌ | ❌ | ⚡ Agent Hooks |
| Multi-Agent Pipeline | ✅ | ❌ | ❌ | ❌ | ✅ Orchestrator + worktree | ✅ Autonomous Agent |
| 命令数量 | 13 | 12 | 13 | 13 | workflows | prompts |
2.3 首次使用三步走
- Claude Code
- Cursor
- Codex
- OpenCode
- Kilo
- Kiro
# 步骤 1：打开 Claude Code 终端
# Hook 自动注入上下文，你可以直接描述任务（也可运行 /start 了解完整流程）
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# AI 会读取规范 → 创建任务 → 调用 Agent 实现 → 自我检查
# 完成后你测试、提交、记录会话即可
# 步骤 1：打开 Cursor，必须先调用
/start
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# AI 会读取规范 → 创建任务 → 实现 → 你手动运行 /trellis-check-backend 检查
# 完成后你测试、提交、记录会话即可
# 步骤 1：Codex 通过 AGENTS.md 提供基础上下文
# 需要运行 $start 获取完整上下文
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# 完成后你测试、提交、记录会话即可
# 步骤 1：打开 OpenCode 终端
# Hook 自动注入上下文，你可以直接描述任务（也可运行 /start 了解完整流程）
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# 完成后你测试、提交、记录会话即可
# 步骤 1：Kilo 通过 .kilocode/rules/ 自动加载项目规范
# 可运行 /start.md workflow 获取完整上下文
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# Kilo Orchestrator Mode 会拆解任务分配给 Code/Architect 等模式
# 完成后你测试、提交、记录会话即可
# 步骤 1：Kiro 通过 .kiro/steering/ 自动加载项目规范
# 选择 Spec 模式生成需求→设计→任务三件套
# 步骤 2：描述你要做什么
"添加用户登录功能"
# 步骤 3：AI 自动工作
# Kiro 按 tasks.md 中的 checklist 逐步实现
# Agent Hooks 可在文件保存时自动触发检查
# 完成后你测试、提交、记录会话即可
2.4 目录结构全貌
your-project/
├── .trellis/ # Trellis 核心目录
│ ├── .developer # 开发者身份 (gitignored)
│ ├── .current-task # 当前活跃任务指针
│ ├── .version # Trellis 版本号
│ ├── .template-hashes.json # 模板文件哈希 (用于 update)
│ ├── workflow.md # 开发工作流指南
│ ├── worktree.yaml # Multi-Agent worktree 配置
│ │
│ ├── spec/ # 项目规范库
│ │ ├── frontend/ # 前端规范
│ │ │ ├── index.md # 规范索引
│ │ │ ├── component-guidelines.md
│ │ │ ├── hook-guidelines.md
│ │ │ ├── state-management.md
│ │ │ ├── type-safety.md
│ │ │ ├── quality-guidelines.md
│ │ │ └── directory-structure.md
│ │ ├── backend/ # 后端规范
│ │ │ ├── index.md
│ │ │ ├── database-guidelines.md
│ │ │ ├── error-handling.md
│ │ │ ├── logging-guidelines.md
│ │ │ ├── quality-guidelines.md
│ │ │ └── directory-structure.md
│ │ └── guides/ # 思维指南
│ │ ├── index.md
│ │ ├── cross-layer-thinking-guide.md
│ │ └── code-reuse-thinking-guide.md
│ │
│ ├── workspace/ # 开发者工作区
│ │ ├── index.md # 工作区总索引
│ │ └── {developer-name}/ # 每人独立目录
│ │ ├── index.md # 个人索引
│ │ └── journal-N.md # 会话日志
│ │
│ ├── tasks/ # 任务目录
│ │ ├── {MM-DD-task-name}/ # 活跃任务
│ │ │ ├── task.json # 任务元数据
│ │ │ ├── prd.md # 需求文档
│ │ │ ├── info.md # 技术设计 (可选)
│ │ │ ├── implement.jsonl # Implement Agent 上下文
│ │ │ ├── check.jsonl # Check Agent 上下文
│ │ │ └── debug.jsonl # Debug Agent 上下文
│ │ └── archive/ # 已归档任务
│ │ └── {YYYY-MM}/
│ │
│ └── scripts/ # 自动化脚本
│ ├── task.py # 任务管理 (14 个子命令)
│ ├── get-context.py # 获取会话上下文
│ ├── get-developer.py # 获取开发者身份
│ ├── init-developer.py # 初始化开发者
│ ├── add-session.py # 记录会话
│ ├── common/ # 公共库
│ │ ├── paths.py
│ │ ├── developer.py
│ │ ├── git-context.py
│ │ ├── task-utils.py
│ │ ├── task-queue.py
│ │ ├── phase.py
│ │ ├── registry.py
│ │ └── worktree.py
│ └── multi-agent/ # 并行开发脚本
│ ├── plan.py
│ ├── start.py
│ ├── status.py
│ ├── create-pr.py
│ └── cleanup.py
│
├── .claude/ # Claude Code 配置
│ ├── settings.json # Hook 和权限配置
│ ├── commands/ # Slash 命令
│ │ └── trellis/ # Trellis 命令集
│ │ ├── start.md
│ │ ├── parallel.md
│ │ ├── record-session.md
│ │ ├── finish-work.md
│ │ ├── onboard.md
│ │ ├── before-backend-dev.md
│ │ ├── before-frontend-dev.md
│ │ ├── check-backend.md
│ │ ├── check-frontend.md
│ │ ├── check-cross-layer.md
│ │ ├── break-loop.md
│ │ ├── create-command.md
│ │ └── integrate-skill.md
│ ├── agents/ # Agent 定义
│ │ ├── dispatch.md
│ │ ├── plan.md
│ │ ├── implement.md
│ │ ├── check.md
│ │ ├── debug.md
│ │ └── research.md
│ ├── hooks/ # Hook 脚本
│ │ ├── session-start.py
│ │ ├── inject-subagent-context.py
│ │ └── ralph-loop.py
│ └── skills/ # Skill 目录
│
├── .cursor/ # Cursor 配置
│ └── commands/
│ └── trellis-*.md # Cursor 版命令集
│
├── AGENTS.md # Codex 入口文件
├── .agents/ # Agent Skills (Codex / OpenCode)
│ └── skills/
│
├── .kilocode/ # Kilo Code 配置
│ ├── rules/ # 项目规则（所有模式通用）
│ ├── workflows/ # Workflow 命令
│ └── skills/ # Agent Skills
│
└── .kiro/ # Kiro 配置
├── steering/ # 项目上下文（Steering 系统）
├── hooks/ # Agent Hooks（事件驱动自动化）
├── prompts/ # 自定义提示词
└── specs/ # Spec-Driven Development 文档