aep-onboard

入门

为 Agentic TypeScript 开发设置环境，并了解 AEP 的思路。阶段 0 会引导你了解思维模型；阶段 1–5 会安装 AEP、验证工具并配置 AEP 的项目防护措施。首次设置时运行一次即可；回访用户若只是重新验证环境，可以跳过阶段 0，直接从阶段 1 开始。

---

阶段 0 — 熟悉概况（仅限首次使用者）

回访用户？ 如果你之前运行过 /aep-onboard，现在只是重新验证环境，请跳至阶段 1。

AEP 不是命令运行器，而是一种工作流：它将_思考_（在控制平面上与 AI 一起决定要构建什么）和_执行_（Agent 根据精确规格在执行平面上构建）分开，二者只通过结构化产物（product-context.yaml、.dev-workflow/signals/ 中的信号文件）沟通，而不共享代码上下文。安装工具却不了解这一模型，只会让你面对空白终端，不知道该先运行哪个技能。

阅读**已安装的概览指南**——这是一份自成一体的 10 分钟入门导览：三个思维模型（控制平面与执行平面、Jeff Patton 故事地图、双会话主会话／工作区模型）、每项技能的作用，以及四条具体路径（新产品／现有项目／单项功能／免手动操作）。

**完成标准：**你已阅读 orientation.md，并能说出下方“后续步骤 — 选择你的路径”中的四条路径哪一条符合你的情况。然后继续阶段 1。

---

阶段 1 — 安装插件

使用 skills CLI 在项目级别安装 AEP v4.1.0，项目使用的每种 Agent 各安装一次。提交已安装的文件，以便为团队锁定版本：

# Run the command for each agent runtime this project uses.
npx -y [email protected] add memorysaver/[email protected] -a claude-code --skill '*' -y
npx -y [email protected] add memorysaver/[email protected] -a codex        --skill '*' -y

这会安装所有 AEP 技能（名称为 aep-*）以及 skills-lock.json 清单——两者都要提交。每种 Agent 运行时都会获得自己的副本；已经采用的共享符号链接布局仍然有效。已提交的技能文件是项目的持久版本锁定；如需升级，请使用所需标签重新运行同一命令，然后检查并提交生成的技能和锁定文件差异。

阶段 1 只安装 AEP。AEP 的项目记录自成一体：/aep-build 会将经验记录在 .dev-workflow/lessons.md 中，/aep-wrap 会将其归档到 lessons-learned/，而 /aep-launch 会重新调用这些经验；可用时，宿主记忆可在此记录基础上加速。可选的第三方集成列于 references/plugins.md，只有用户提出要求时才添加。

---

阶段 1.5 — 接入 Agent 指令文件

指令文件与 AEP 一起进行版本管理。此技能在 templates/ 下提供三个模板：AGENTS.md.tmpl（通用工作约定、包含固定版本和 /aep-easy-explain 注册表的 ## AEP Workflow 部分，以及指向 project-convention/ 的 ## Project Context）、CLAUDE.md.tmpl（@AGENTS.md），以及 project-convention/README.md.tmpl（约定索引：项目如何使用 AEP、docs/ 路由表、AEP 负责的目录，以及如何添加约定）。AGENTS.md 的第一行是标记 ``；/aep-scaffold 的审计会读取该标记，而 references/migrations.md 会据此确定升级步骤。

• 尚无 AGENTS.md： 将三个模板原样复制到相应位置（project-convention/README.md 放在仓库根目录），并与安装一起提交。
• 已有 AGENTS.md： 读取其中的标记，并按顺序应用 references/migrations.md 中从该标记对应版本到固定版本的每个部分。项目特定内容移至 project-convention/<topic>.md，每个主题单独一个文件，并从 README 链接；AGENTS.md 中不保留任何项目特定内容。手写的 CLAUDE.md 必须先手动合并到 AGENTS.md，然后才能将其改为 @AGENTS.md。
• 仅使用 Codex 的仓库： 跳过 CLAUDE.md。

验证： head -1 AGENTS.md 输出固定版本的标记；在安装了 Claude Code 的位置，head -1 CLAUDE.md 输出 @AGENTS.md；project-convention/README.md 存在。

---

Phase 2 — 验证必需工具

以下工具各自在 Agent 工作流中发挥作用：git 提供版本控制和 worktree（每个并行 Agent 使用一个隔离的工作树），Node/npm 用于运行固定版本的安装程序和 OpenSpec，bun 用于运行 TypeScript 单仓库，openspec 支持规范驱动开发，执行器（claude 或 codex）用于运行实现 Agent，而 gh 用于发布 PR。Claude Code 项目还需要 jq 来运行 AEP 的并发钩子。tmux 可选：启动优先使用原生方式（参见 /aep-executor）；tmux 仅用于固定版本的旧版模式和通用主机回退模式。

运行此检查：

# Required: at least one executor (claude OR codex)
command -v claude >/dev/null 2>&1 || command -v codex >/dev/null 2>&1 \
  && echo "executor:      OK" || echo "executor:      MISSING (install claude or codex)"

# Required: everything else
for cmd in node npm bun git gh openspec; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK ($(command -v "$cmd"))" || echo "MISSING"
done
node -e 'const [M,m]=process.versions.node.split(".").map(Number); process.exit(M>20||(M===20&&m>=19)?0:1)' \
  && echo "node version:   OK (>=20.19)" || echo "node version:   TOO OLD (need >=20.19)"

# Required only when Claude Code skills are installed: concurrency hooks parse tool input with jq
if [ -e .claude/skills/aep-onboard/SKILL.md ]; then
  printf "%-15s" "jq:"
  command -v jq >/dev/null 2>&1 && echo "OK ($(command -v jq))" || echo "MISSING (required for Claude hooks)"
fi

# Optional (legacy/pinned-tmux mode only): tmux
printf "%-15s" "tmux:"
command -v tmux >/dev/null 2>&1 && echo "OK ($(command -v tmux))" || echo "MISSING (optional — only the legacy launch mode needs it)"

安装缺失的工具：

工具	用途	安装
node/npm	固定版本的技能安装程序 + OpenSpec 运行时	通过平台首选的版本管理工具安装 Node >= 20.19
git	版本控制 + worktree	xcode-select --install（macOS）
bun	包管理器和运行时	curl -fsSL https://bun.sh/install | bash
claude	执行器：Claude Code CLI	npm install -g @anthropic-ai/claude-code
codex	执行器：OpenAI Codex CLI	npm install -g @openai/codex （claude 的替代选项）
gh	用于 PR 的 GitHub CLI	brew install gh
openspec	规范驱动开发	npm install -g @fission-ai/openspec@latest
jq	Claude Code 并发钩子的 JSON 解析	brew install jq / apt-get install jq （仅 Claude）
tmux	终端复用器（可选 — 旧版模式）	brew install tmux

所有必需工具（Node >=20.19、npm、执行器、bun/git/gh/openspec，以及 Claude 安装所需的 jq）在继续之前都必须显示 OK。你至少需要一个执行器（claude 或 codex），不必两者都有。tmux 可以显示 MISSING；这没关系，因为启动优先使用原生方式。

关于并行运行的说明： 每个并行功能 Agent 都在自己的 git worktree 中运行，路径为 .feature-workspaces/<name>/，并使用自己的 feat/<name> 分支。各个 worktree 共享底层 .git/objects（不会重复保存历史记录），但每个都会在磁盘上额外占用一份完整的工作树副本；并行运行多个 Agent 时请预留足够空间。

---

阶段 3 — 验证可选工具

for cmd in cmux agent-browser portless; do
  printf "%-15s" "$cmd:"
  which $cmd >/dev/null 2>&1 && echo "OK ($(which $cmd))" || echo "MISSING (optional)"
done

工具	用途	安装
cmux	可点击的标签页复用器，用于监视旧模式的 tmux 会话——可选；仅在固定使用 tmux 时才用到	bun add -g cmux
agent-browser	浏览器自动化测试	Claude Code 插件：agent-browser@agent-browser
portless	端口管理（.localhost）	bun add -g portless

**cmux 只是为了方便。**没有它，固定的 tmux 工作区仍可运行完整的监控和执行中反馈循环——使用 tmux attach -t <name> 进行连接。 请参阅 /aep-executor。

这些工具都是可选的——没有它们，工作流也能运行，但有了它们会更完善。在 macOS 上，先确认只需一条命令即可启动页面且不会导致 Chrome 崩溃，再启用一次 agent-browser：

agent-browser navigate about:blank

如果 macOS 显示包含 _RegisterApplication、TransformProcessType 或 abort() called 的 Google Chrome 崩溃报告，请停用 agent-browser，改用非浏览器检查方式（curl、单元测试、用户提供的截图，或宿主 Agent 的浏览器工具），直到本地 Chrome 与 agent-browser 的组合恢复正常。

---

阶段 4 — 配置 AEP 项目防护措施（仅限 Claude Code）

如果此项目未安装 .claude/skills/aep-*，请跳过此阶段。Codex 通过已安装的 AEP 指令和原生 Agent 角色强制执行工作流；它不需要 .claude/settings.json。

对于 Claude Code 项目，请安装 AEP 的两个并发钩子。它们可防止并行工作区 Agent 破坏 product-context.yaml。可选的第三方插件不属于基础接入范围；AEP 的核心工作流和回退路径无需这些插件即可运行。

写入内容

如果 .claude/settings.json 存在，请先读取，然后将 references/settings-template.json 中的 hooks.PreToolUse 条目合并到其中（如果文件不存在，则根据模板创建）。保留所有现有设置和钩子。

验证两个钩子已写入：

jq '[.hooks.PreToolUse[].matcher]' .claude/settings.json
# expect an array containing both "Edit|Write" and "Bash"

**并发协议钩子：**它们会阻止工作区 Agent 编辑、写入或提交 product-context.yaml，并将其引导至信号文件。这是一种纵深防御措施——技能指令也会指示 Agent 使用信号，但钩子能捕获模型偏移。只有主会话（/aep-wrap、/aep-dispatch、/aep-reflect）会更新 YAML。

合并规则

• 将新条目合并到现有键中，并保留其他所有设置（permissions、env 等）。
• 如果 hooks.PreToolUse 已存在，请追加这些钩子条目，而不是替换现有钩子。
• 如果文件不存在，请根据仅包含钩子的模板创建。

---

阶段 5 — 验证环境

echo "=== Core Tools ==="
command -v claude >/dev/null 2>&1 || command -v codex >/dev/null 2>&1 \
  && echo "executor:      OK" || echo "executor:      MISSING (claude or codex)"
for cmd in node npm bun git gh openspec; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK" || echo "MISSING"
done
node -e 'const [M,m]=process.versions.node.split(".").map(Number); process.exit(M>20||(M===20&&m>=19)?0:1)' \
  && echo "node version:   OK (>=20.19)" || echo "node version:   TOO OLD (need >=20.19)"
if [ -e .claude/skills/aep-onboard/SKILL.md ]; then
  printf "%-15s" "jq:"
  command -v jq >/dev/null 2>&1 && echo "OK" || echo "MISSING (required for Claude hooks)"
fi
echo ""
echo "=== Optional Tools ==="
for cmd in tmux cmux agent-browser portless; do
  printf "%-15s" "$cmd:"
  command -v "$cmd" >/dev/null 2>&1 && echo "OK" || echo "MISSING (optional)"
done
echo ""
echo "=== Git Repo ==="
git rev-parse --is-inside-work-tree >/dev/null 2>&1 && echo "git repo: OK" || echo "Not a git repo — run: git init"
git worktree list 2>/dev/null | head -5

如果所有核心工具均显示 OK，则环境已就绪。

集成分支（单分支模式与双分支模式）

AEP 会将所有功能开发集成到一个集成分支（各项技能中均为 $BASE）。根据 /aep-git-ref →“Integration Branch”解析 $BASE（优先使用配置覆盖值，然后自动检测——标准的 main/develop 情况无需配置），并报告此仓库采用的模式：develop → 双分支模式（main 仅用于晋升到生产环境）；否则为基于 main 的单分支模式。

如果集成分支名称不是标准名称（不是 main/develop，例如 staging 或 integration），请一次性设置仓库本地覆盖值——配置命令以及标准情况保持不固定配置的原因，见同一 /aep-git-ref 部分（这样仓库就能从单分支模式扩展为双分支模式，无需重新配置）。

启用原生启动模式（推荐）

/aep-launch 和 /aep-autopilot 会自动选择启动模式——优先使用原生模式，仅在固定配置时使用 tmux。Claude Code 无需设置（默认使用后台子 Agent，必要时回退到后台会话）。要启用最佳 Codex 模式，请将两个 AEP 角色文件（aep-builder.toml、aep-evaluator.toml）提交到项目的 .codex/agents/ 目录——TOML 模板和完整的启动模式说明见 /aep-executor（references/codex-native.md）。更喜欢传统的 tmux+cmux 工作流？固定为该模式：git config aep.executor-backend tmux。

---

后续步骤 — 选择你的路径

下一步取决于你的情况。选择与你要做的事情相符的路径。每条路径的完整说明（包括各步骤为何按此顺序排列）见已安装的入门指南。

路径 A — 从零开始打造新产品

你有一个想法和一个全新的仓库。

/aep-envision  →  /aep-map  →  /aep-validate  →  /aep-scaffold  →  /aep-autopilot

/aep-autopilot 为可选项——你也可以通过 /aep-dispatch → /aep-design → /aep-launch → /aep-build → /aep-wrap 手动执行相同的循环。

路径 B — 为现有项目接入

你已有代码库，并希望为其添加 AEP 工作流。

/aep-scaffold  →  /aep-dispatch  →  /aep-design  →  /aep-launch  →  /aep-build  →  /aep-wrap

/aep-scaffold 会为现有代码添加 Agent 基础设施（OpenSpec、工作区钩子、E2E 骨架）；之后可用 /aep-envision 补充产品背景。

路径 C — 单个功能，不需要产品背景

你只想通过 AEP 工作流交付一个功能。

/aep-design  →  /aep-launch  →  /aep-build  →  /aep-wrap

/aep-design 会在集成分支（$BASE）上生成 OpenSpec 变更；其余工作会在 feat/<name> 上的隔离 worktree 中进行，之后由 /aep-wrap 归档并移除该 worktree。

路径 D — 无需干预的自主模式

你已有经过验证的产品背景，想去喝杯咖啡。

/aep-autopilot

只需一条命令。只有在设计升级处理或层级门禁失败时才会暂停。直接运行 /aep-autopilot，查看完整的运行周期与暂停协议。

仍不确定该选哪条路径？ 使用已安装的入门指南中的决策规则。

---

护栏

• 从项目根目录运行——工具和插件会依据当前环境进行验证。
• 可随时重新运行——可安全地重新运行，以验证环境是否仍然完整。回访用户可以跳过第 0 阶段（入门说明），直接进入第 1 阶段。
• 仅执行检查——此技能会验证并安装工具；不会搭建项目骨架或修改代码。

---

了解更多

• 已安装的入门指南 — 心智模型、技能概览和四种入门路径；此技能始终提供离线访问。
• /aep-git-ref — worktree 生命周期、分支命名、按任务提交的模式、$BASE 解析和恢复。
• /aep-autopilot — 自主运行周期、监控、升级处理和暂停协议。
• AEP 公开文档 — 网络可用时可查阅扩展词汇表、决策和架构资料。