erniker/understudy
GitHub: erniker/understudy
一个为 GitHub Copilot CLI、VS Code Copilot、Claude Code 和 Cursor 自动生成专业化 AI Agent 团队配置的系统，让 AI 工具以角色分工协作的方式参与软件开发全流程。
Stars: 1 | Forks: 0
# 🎭 Understudy — 一个 AI，扮演所有角色
## 安装说明
**单行命令** (Linux, macOS, Windows Git Bash / WSL):
```
curl -fsSL https://raw.githubusercontent.com/erniker/understudy/main/install.sh | bash
```
这会下载最新版本，将其安装到 `~/.understudy/` 目录下，并将
`understudy` 命令添加到你的 PATH 中。
**特定版本：**
```
curl -fsSL https://raw.githubusercontent.com/erniker/understudy/main/install.sh | bash -s -- --version v1.0.0
```
**手动安装（克隆）：**
```
git clone https://github.com/erniker/understudy.git
cd understudy
chmod +x wizard.sh
```
## 快速入门
```
# 在任何项目中部署 Understudy
cd /path/to/your/project
understudy
# → 选择平台：Copilot, Claude Code, Cursor
# 然后打开你的 AI 工具
claude # Claude Code
copilot # GitHub Copilot CLI
cursor . # Cursor
```
### 零问题部署 (`--here`)
已经在现有 repo 中，不想回答向导的
问题？使用 `--here` — Understudy 会根据你工作目录中的文件推断项目名称、描述、
技术栈、repository URL 和 PM：
```
cd /path/to/your/project
understudy --here # shows inferred values, asks one confirmation
understudy --here --yes # fully unattended, no prompts
```
推断的内容：
- **Project name (项目名称)** — 来自文件夹名称或根目录的 `package.json`
- **Description (描述)** — 来自 `package.json` 或 `README.md` 的第一段
- **Stack (技术栈)** — Node.js / React / Vue / Angular / .NET / Python / Terraform / Docker / Shell
- **Repository URL (仓库 URL)** — 来自 `git remote get-url origin`
- **PM (项目经理)** — 来自 `git config user.name`
向导会打印所有 9 项设置的编号摘要（与
交互式向导询问的问题相同），并在确认
提示处提供三个选项：
- **`Y`** — 使用推断出的设置进行部署（默认）。
- **`n`** — 取消。
- **`e`** — 交互式编辑任何字段。你输入字段编号
（`1`-`9`），提供新值，重复操作直到满意。然后输入 `d` 进行
部署或输入 `q` 退出。
无法推断的选项会应用默认值：`split` guardrails，启用所有三个
平台，将文件提交到 repo。如果你需要自定义这些设置，请在不使用 `--here` 的情况下运行以使用
完整的交互式向导。
### 安装选项
| 标志 | 描述 |
|---|---|
| `--version ` | 安装特定版本（例如 `v1.2.0`） |
| `--dir ` | 自定义安装目录（默认：`~/.understudy`） |
| `--no-path` | 跳过 PATH 设置 |
| `--uninstall` | 从系统中移除 Understudy |
### 自动更新检查
当你运行 `understudy` 时，它会检查 GitHub 上是否有新版本。
如果存在较新的版本，它会询问你是否要立即更新。
要禁用此检查（适用于 CI 或离线环境）：
```
export UNDERSTUDY_SKIP_UPDATE_CHECK=1
```
## 这是什么？
一个能够自动生成 **GitHub Copilot CLI**、**VS Code**、**Claude Code** 和 **Cursor** 作为完整开发团队工作所需的
所有配置的系统：
| 成员 | 角色 | 专长 |
|---|---|---|
| 🏛️ **Architect** | 解决方案架构师 | 系统设计、API、数据库、云 |
| ⚙️ **Backend** | 后端开发者 | .NET, Node.js, C#, TypeScript, Python, Bash |
| 🎨 **Frontend** | 前端开发者 | React, TypeScript, UX/UI, 可访问性 |
| 🚀 **DevOps** | DevOps 工程师 | Azure, AWS, Docker, K8s, Terraform, CI/CD |
| 🔒 **Security** | 安全专家 | OWASP, 威胁建模, 合规性, IAM |
| 🧪 **QA** | QA 工程师 | 测试 .NET, Node.js, Python, E2E, 契约测试 |
## 核心概念
### 1. AGENTS.md — "团队成员是谁"
位于项目根目录的文件，定义了可以在 Copilot CLI 中使用 `/agent` 选择的代理。
每个代理都有名称、角色、专长和行为规则。
### 2. .github/copilot-instructions.md — "项目规则"
Copilot 在每次会话中**自动**加载的全局指令。
定义了项目上下文、约定和工作流。
### 3. .github/instructions/*.instructions.md — "每位成员的工作方式"
每个角色的模块化指令文件。使用 `/instructions` 激活
或与相应的代理一起加载。它们包含每个成员的详细个性、
代码标准和检查清单。
### 4. 并行子代理 — "分而治之"
Copilot CLI 可以启动并行工作的子代理（task tool）。
非常适合后端和前端同时实现，同时
DevOps 准备基础设施。
### 5. 上下文文件 — "会话间的记忆"
文件 `docs/session-log.md`、`docs/spec.md` 和 `docs/decisions.md`
充当持久记忆。在每次会话开始时代理会读取它们；
在结束时，代理会更新它们。这能节省 token 并避免重复信息。
### 6. 🛡️ Guardrails — "我们绝不做什么"
所有代理都遵守的安全和行为限制。
它们涵盖 8 个类别：安全、范围、流程、破坏性操作、
数据/PII、质量、环境和文档。它们是**不可协商的**，并且
随向导自动部署。
### 7. 🔒 仅限本地模式 — "将 AI 配置排除在 git 之外"
可选。向导可以将生成的 AI 配置（`AGENTS.md`、
`CLAUDE.md`、`.github/instructions/`、`.claude/`、`.cursor/`…）和/或
会话记忆文件（`docs/spec.md`、`docs/decisions.md`、
`docs/session-log.md`）追加到项目的 `.gitignore` 中，使其保留在本地。
适用于 AI 工具配置需要保密的企业 repo，或者不想暴露内部工作流的开源
项目。通过 `understudy.yaml` 中的 `git.local_config` / `git.local_memory` 进行切换 — 请参阅
[docs/09-configuration.md](docs/09-configuration.md#local-only-mode)。
## Guardrails
Guardrails 保护团队免受以下情况的影响：
- 泄露秘密或敏感数据
- 未经确认的破坏性操作
- 未经变更控制的生产环境更改
- 没有规范、没有测试或没有审查的代码
- 代理之间的范围违规
### 部署模式
| 模式 | 描述 |
|---|---|
| 🔀 **split** (推荐) | 关键 guardrails 始终在 `copilot-instructions.md` 中处于活动状态 + 完整细节文件在 `guardrails.instructions.md` 中 |
| 📦 **embedded** | 仅关键 guardrails 嵌入在 `copilot-instructions.md` 中（更轻量，无单独文件） |
### Split 与 Embedded 的实际区别
| 方面 | 🔀 split | 📦 embedded |
|---|---|---|
| **执行级别** | 关键 guardrails 始终处于活动状态 **并且** 完整的 guardrails 可在专用文件中使用 | 仅关键 guardrails 始终处于活动状态 |
| **可见性** | 更高：团队可以在 `guardrails.instructions.md` 中审查完整的 guardrails | 较低：全局指令中仅可见缩减后的集合 |
| **维护** | 更容易在不臃肿全局指令的情况下演进完整的 guardrails | 更简单的文件结构，但详细策略的空间较少 |
| **最适用于** | 受监管的团队、大型 repo、多代理工作流、更严格的治理 | 小型/快速项目、轻量级设置、希望开销最少的团队 |
| **权衡** | 更多文件和稍多的结构 | 对非关键规则的显式覆盖较少 |
**经验法则：**
- 当你想要更强的治理、更好的可审计性和更清晰的团队一致性时，选择 **split**。
- 当速度和简单性比策略深度更重要时，选择 **embedded**。
该模式在向导期间选择，可以通过编辑 `understudy.yaml` 来更改：
```
guardrails:
mode: "split" # "split" or "embedded"
```
### 类别
| # | 类别 | 保护内容 |
|---|---|---|
| 1 | 🛡️ 安全 | 无秘密，无绕过，强制输入验证 |
| 2 | 🎯 范围 | 每个代理的文件所有权，跨越边界需要提供理由 |
| 3 | 📋 流程 | 规范优先（bug 修复/紧急情况除外），记录决策 |
| 4 | 💥 破坏性 | 删除、清除或撤销前需 PM 确认 |
| 5 | 🔒 数据/PII | 无真实数据，测试中使用合成数据，GDPR |
| 6 | 🏗️ 质量 | 自我审查，适当的测试，命名，错误处理 |
| 7 | ⚠️ 环境 | 提升 (Promotion) 顺序 dev→prd，强制 IaC，禁止手动更改 |
| 8 | 📝 文档 | ADRs，session-log，更新规范 |
## 系统结构
```
understudy/
├── wizard.sh # 🧙 The wizard — deploys Understudy
├── install.sh # 📦 One-liner curl installer
├── run_tests.sh # 🧪 Local test runner
├── understudy.yaml # ⚙️ Global configuration
├── templates/ # 📋 Base templates
│ ├── AGENTS.md # Copilot: team definition
│ ├── CLAUDE.md # Claude: global instructions
│ ├── .github/ # Copilot / VS Code
│ │ ├── copilot-instructions.md
│ │ ├── instructions/
│ │ │ ├── architect.instructions.md
│ │ │ ├── backend.instructions.md
│ │ │ ├── frontend.instructions.md
│ │ │ ├── devops.instructions.md
│ │ │ ├── security.instructions.md
│ │ │ ├── qa-engineer.instructions.md
│ │ │ └── guardrails.instructions.md
│ │ └── prompts/
│ │ ├── start-session.prompt.md
│ │ ├── end-session.prompt.md
│ │ ├── design-feature.prompt.md
│ │ └── security-review.prompt.md
│ ├── .claude/ # Claude Code
│ │ ├── agents/
│ │ │ ├── architect.md, backend.md, frontend.md
│ │ │ ├── devops.md, security.md, qa.md
│ │ ├── commands/
│ │ │ ├── start-session.md, end-session.md
│ │ │ ├── design-feature.md, security-review.md
│ │ ├── hooks/
│ │ │ └── guardrails-check.sh
│ │ └── settings.json
│ ├── .cursor/ # Cursor
│ │ ├── agents/
│ │ │ ├── architect.md, backend.md, frontend.md
│ │ │ ├── devops.md, security.md, qa-engineer.md
│ │ └── rules/
│ │ ├── understudy-global.mdc
│ │ └── guardrails.mdc
│ └── docs/
│ ├── spec.md
│ ├── decisions.md
│ ├── session-log.md
│ └── team-roster.md
├── roles/ # 🎭 Optional roles catalog
│ ├── data-engineer.instructions.md
│ ├── git-specialist.instructions.md
│ ├── mobile-engineer.instructions.md
│ ├── ml-engineer.instructions.md
│ ├── repo-documenter.instructions.md
│ ├── shell-scripting.instructions.md
│ ├── tech-writer.instructions.md
│ └── sre.instructions.md
├── tests/ # 🧪 bats test suite
│ ├── unit/ # config_read, detect, deploy_file, guardrails
│ ├── hooks/ # guardrails-check.sh tests
│ ├── integration/ # end-to-end wizard deployment
│ ├── fixtures/ # fake project structures
│ └── lib/helpers.bash # shared test helpers
└── docs/ # 📚 Documentation
├── README.md # Index
├── 01-introduction.md
├── 02-quick-start.md
├── 03-platform-comparison.md
├── platforms/
│ ├── copilot-cli.md
│ ├── vscode-copilot.md
│ ├── claude-code.md
│ └── cursor.md
├── 08-cross-platform-workflows.md
├── 09-configuration.md
└── 10-troubleshooting.md
```
## 文档
完整文档位于 [`docs/`](docs/README.md) 目录下，其组织方式允许在作为静态站点发布时无需重构。
| 部分 | 内容 |
|---|---|
| [简介与核心概念](docs/01-introduction.md) | 心智模型、代理、规范驱动开发、持久记忆、guardrails、角色目录、生成的文件 |
| [快速入门](docs/02-quick-start.md) | 安装、首次会话、扩展团队 |
| [平台功能矩阵](docs/03-platform-comparison.md) | 每个工具开箱即用的支持内容 |
| [GitHub Copilot CLI](docs/platforms/copilot-cli.md) | 设置、命令、完整功能流程、子代理、提示 |
| [VS Code Copilot](docs/platforms/vscode-copilot.md) | `applyTo` globs、提示文件、开始 → 工作 → 结束流程 |
| [Claude Code](docs/platforms/claude-code.md) | 代理、斜杠命令、拒绝列表、PreToolUse hook、添加命令 |
| [Cursor](docs/platforms/cursor.md) | 规则 (MDC)、代理面板、创建你自己的规则 |
| [跨平台工作流](docs/08-cross-platform-workflows.md) | 混合设置与共享会话协议 |
| [配置参考](docs/09-configuration.md) | 完整的 `understudy.yaml` 参考 |
| [故障排除与常见问题](docs/10-troubleshooting.md) | 常见问题、模型选择、报告 Bug |
## 向导命令
| 命令 | 描述 |
|---|---|
| `understudy` | 完整的交互式部署 |
| `understudy --here` | 使用从 repo 推断的值在当前目录中部署（编号摘要，可通过 `e` 编辑） |
| `understudy --here --yes` | 与 `--here` 相同，但跳过确认提示（完全无人值守） |
| `understudy --add-member` | 添加团队成员（数据工程师、QA 等） |
| `understudy --create-role` | 从头创建自定义角色 |
| `understudy --help` | 显示帮助 |
## 集成到现有项目与 Monorepo 中
向导会自动检测现有项目并进行适配：
| 场景 | 行为 |
|---|---|
| 🆕 文件夹不存在 | 创建具有完整结构的新项目 |
| 🔄 现有项目 | 集成 Understudy 而不触碰现有文件 |
| ⚠️ 已包含 Understudy | 重新部署：仅添加缺失的文件 |
### 自动技术栈检测
向导会扫描最多 3 层深度以检测技术：
| 技术 | 标记 | 示例 |
|---|---|---|
| .NET | `*.csproj`, `*.sln` | `.NET: services/api-customers (ApiCustomers)` |
| Node.js | `package.json` (不包含 React/Vue/Angular) | `Node.js: services/api-notifications` |
| React | 包含 `"react"` 的 `package.json` | `React: frontend/web-app` |
| Vue | 包含 `"vue"` 的 `package.json` | `Vue: frontend/admin` |
| Angular | 包含 `"@angular/core"` 的 `package.json` | `Angular: frontend/portal` |
| Python | `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` | `Python: services/ml-scoring` |
| Terraform | `*.tf` | `Terraform: infra/terraform` |
| Docker | `Dockerfile`, `docker-compose.yml` | `Docker: 4 Dockerfiles` |
| Shell | `*.sh`, `*.bash`, `*.zsh` | `Shell` (自动添加 shell-scripting 角色) |
### Monorepo 支持
当检测到 2 个或更多独立项目时，技术栈会被标记为 **Monorepo**：
```
Monorepo: .NET(2) + Node.js + React(2) + Python + Terraform + Docker
Components found:
• .NET: services/api-customers (ApiCustomers)
• .NET: services/api-policies (ApiPolicies)
• React: frontend/web-app
• Node.js: services/api-notifications
• Python: services/ml-scoring
• Terraform: infra/terraform
• Docker: 4 Dockerfiles
• Docker Compose: ./
```
检测到的技术栈会作为默认值预填充，从而在设置过程中为你节省时间。
## 推荐工作流
```
PM writes spec.md
│
▼
/agent Architect ──── designs solution ──── docs/decisions.md
│
▼
/agent Security ───── threat model
│
├──────────────────────┐
▼ ▼
/agent Backend /agent Frontend
(implements APIs) (implements UI)
│ │
└──────────┬───────────┘
▼
/agent QA
(test plan + tests)
│
▼
/agent DevOps
(infra + CI/CD + deploy)
│
▼
/agent Security
(final review)
│
▼
session-log.md updated
```
## 如何添加新角色
`roles/` 文件夹是系统的**官方可选角色目录**。6 个核心角色（Architect, Backend, Frontend, DevOps, Security, QA）始终从 `templates/` 部署；`roles/` 中的角色是附加的，由你自行选择。
**包含的可选角色：**
| 角色 | 使用 |
|---|---|
| 🐉 **caveman** | 节省 token 的文本。去除冗余修饰；保留代码/路径/URL。通过 `--caveman` 选择启用。请参阅 [Caveman 模式](docs/11-caveman-mode.md)。 |
| 📊 **data-engineer** | ETL/ELT pipelines，数据仓库，流处理，数据治理 |
| 🌿 **git-specialist** | Git 工作流，分支策略，PR 规范，发布纪律 |
| 📱 **mobile-engineer** | iOS/Android 应用，React Native, Flutter |
| 🤖 **ml-engineer** | ML 模型，MLOps，LLMs，RAG，负责任的 AI |
| 📖 **repo-documenter** | 代码库理解，架构文档，入职指南 |
| 🐚 **shell-scripting** | Bash/sh 自动化，跨平台脚本，ShellCheck 最佳实践 |
| 📝 **tech-writer** | 技术文档，API 文档，教程，Diataxis |
| 🧭 **sre** | SLOs，可观测性，事件响应，混沌工程 |
**自动部署：** 向导始终包含 `git-specialist` 和
`repo-documenter`。如果在你的项目中检测到 shell 脚本（`*.sh`、`*.bash`、`*.zsh`），
`shell-scripting` 将被自动添加。所有的角色都会部署到
你选择的每个平台（Copilot、Claude、Cursor）。
**如何添加更多：**
1. **从现有目录中**：`understudy --add-member` → 从菜单中选择（适用于 Copilot、Claude 和 Cursor 项目）
2. **创建新角色**：`understudy --create-role` → 保存在 `roles/` 中以便复用
3. **手动方式**：在 `roles/` 中创建一个 `name.instructions.md` 文件，遵循现有格式
## 给项目经理的提示
- 为 Architect 使用 **Claude Opus** (`/model`) — 更好的设计推理能力
- 为 Backend/Frontend 使用 **Claude Sonnet** — 速度/质量的良好平衡
- 为快速的 DevOps 任务使用 **Claude Haiku** — 经济高效
- 在每次会话结束时始终要求更新 `session-log.md`
- 规范是神圣的：如果范围发生变化，请先更新规范
## 配置与覆盖
系统使用具有优先级层次的 `understudy.yaml` 配置文件：
```
1. Wizard defaults (built-in) ← lowest priority
2. ~/.understudy/understudy.yaml (installed) ← global defaults
OR understudy.yaml next to wizard.sh (cloned) ← if installed manually
3. understudy.yaml in the project ← per-project override (highest)
```
覆盖示例：你的项目需要为 Security 使用 Opus，因为它是金融科技：
```
# my-project/understudy.yaml
models:
security: "claude-opus-4.6" # override: more reasoning for fintech
platforms:
copilot: true
claude: true # or false if you only use one platform
cursor: true
guardrails:
mode: "embedded" # override: only critical guardrails for lighter project
```
## 兼容性：Copilot CLI + VS Code + Claude Code + Cursor
Understudy 适用于**所有四个平台** — 在部署期间选择一个或多个：
| 特性 | Copilot CLI | VS Code | Claude Code | Cursor |
|---|---|---|---|---|
| 全局指令 | ✅ 自动加载 | ✅ 自动加载 | ✅ CLAUDE.md | ✅ `.cursor/rules/` |
| 角色指令 | ✅ `/instructions` | ✅ 根据 `applyTo` 自动应用 | ✅ `.claude/agents/` | ✅ `.cursor/agents/` |
| Guardrails | ✅ 自动 + `/instructions` | ✅ 自动应用 (`**`) | ✅ CLAUDE.md + hooks | ✅ `guardrails.mdc` |
| 代理选择 | `/agent` | 结合上下文对话 | 按名称调用 | 代理面板 |
| 可复用提示 | N/A | ✅ `.github/prompts/` | ✅ `/project:command` | N/A |
| 团队定义 | ✅ AGENTS.md | ✅ AGENTS.md | ✅ `.claude/agents/` | ✅ `.cursor/agents/` |
| 文件保护 | N/A | N/A | ✅ `settings.json` 拒绝 | N/A |
| 安全 hooks | N/A | N/A | ✅ `.claude/hooks/` | N/A |
### 在 VS Code 中
- 指令根据你正在编辑的文件**自动**应用
（得益于每个 `.instructions.md` 文件中的 `applyTo` frontmatter）
- `.github/prompts/` 中的提示可作为可复用提示使用
- 使用 "Start Session" 和 "End Session" 提示进行上下文流控制
### 在 Claude Code 中
- 打开项目时会自动加载 `CLAUDE.md`
- 代理位于 `.claude/agents/` — 按名称调用它们
- 命令位于 `.claude/commands/` — 通过 `/project:name` 使用它们
- guardrails hook 会自动阻止破坏性操作
- `settings.json` 保护敏感文件 (.env, keys, secrets)
### 在 Cursor 中
- 全局规则 (`.cursor/rules/`) 会在每次会话中**自动**应用
- 代理位于 `.cursor/agents/` — 从 Agent 面板调用它们
- guardrails 位于 `.cursor/rules/guardrails.mdc` — 始终处于活动状态
- 每个代理都在 frontmatter 中配置了其模型（`auto`、`fast` 或特定模型）
### 各平台对应的文件
**Copilot / VS Code:**
```
.github/copilot-instructions.md → Always active (includes critical guardrails)
.github/instructions/*.instructions.md → By file type (applyTo)
.github/instructions/guardrails.instructions.md → Always active (applyTo: "**")
.github/prompts/*.prompt.md → Invocable from Copilot Chat
AGENTS.md → Read as context
```
**Claude Code:**
```
CLAUDE.md → Always active (includes critical guardrails)
.claude/agents/*.md → Agents by role (with frontmatter)
.claude/commands/*.md → Commands (/project:name)
.claude/settings.json → Permissions and hooks
.claude/hooks/guardrails-check.sh → Hook PreToolUse
```
**Cursor:**
```
.cursor/agents/*.md → Agents by role (with frontmatter)
.cursor/rules/understudy-global.mdc → Global rules (always active)
.cursor/rules/guardrails.mdc → Guardrails (always active)
```
## 贡献
欢迎贡献。在发起 PR 之前请阅读[贡献指南](CONTRIBUTING.md) — 它包含提交约定、版本控制、CHANGELOG 维护和审查流程。
要报告错误或提出改进建议，请使用[议题模板](https://github.com/erniker/understudy/issues/new/choose)。
要报告安全漏洞，请参阅[安全策略](SECURITY.md)。
本项目遵循[贡献者公约](CODE_OF_CONDUCT.md)作为其行为准则。
## 致谢
- **Caveman 模式**（`caveman` 角色和 `understudy-compress` 脚本）
的灵感来源于 [JuliusBrussee/caveman](https://github.com/JuliusBrussee/caveman) —
感谢其作者关于节省 token 的 AI 文本的最初构想，
以及为我们的移植提供信息的开源 prompt 模式。请参阅
[docs/11-caveman-mode.md](docs/11-caveman-mode.md) 了解我们改编了哪些内容，
以及我们有意未包含哪些功能。
标签：AI开发助手, AI智能体, AI角色扮演, Claude Code, Cursor IDE, GitHub Copilot, LLM开发工具, PyRIT, QA测试, Shell脚本, Subfinder, 代码助手, 代码安全, 后端开发, 多智能体系统, 大语言模型应用, 威胁情报, 开发效能提升, 开发者工具, 批量测试, 漏洞枚举, 特权提升, 自动化代码生成, 自动化部署, 跨平台工具, 软件架构, 软件研发自动化, 防御加固, 项目初始化