opc-agent-team

English | 中文

opc-agent-team

A set of 33 role cards for one-person companies (OPC): QA, design, engineering, growth, customer success, executive review, risk control and market insight, written as AI agent prompts. Each card runs as a Claude Code subagent or can be handed to Codex or any agent that reads Markdown. Cards are generic; everything project-specific lives in your own project-profile.md. Default posture is read-only, test accounts and fake data only.

一人公司 AI 角色团

把一人公司需要的各路岗位做成可点名运行的 AI 代理角色卡：33 个岗位，覆盖质量、设计、研发、增长、客户成功、经营评审、风控和洞察。适合小型 SaaS、微信小程序 + Web 管理后台这类产品，不绑定任何具体项目。

三条设计原则：

• 角色卡是通用的，项目差异只写进你自己的 project-profile.md，每个角色开工先读它。
• 每个角色只回答自己那一类问题，结论必须有证据（截图、代码位置、数据），代理的报告只算待核实线索。
• 默认只读，只用测试账号和假数据；发布、发消息、生产写入、付费、改价一律不做，只出建议和文案。

岗位总表

5 分钟上手

1. 复制 project-profile.template.md 为你项目根目录下的 project-profile.md，按实际情况填写产品形态、测试账号获取方式、可写范围、禁止动作、发版节奏、关键指标。密码不要写进去，只写获取方式。

2. 构建并安装角色：

   python3 scripts/build.py && cp dist/claude-code/agents/*.md ~/.claude/agents/
   

   想只在某个项目内使用，把目标改成该项目的 .claude/agents/。

3. 先点名 chief-of-staff，告诉它这次的场景（例如“下周三发版”），它会对照 playbooks/ 选岗位并填写 templates/run-plan.md。

4. 按计划逐个点名岗位，每个岗位按 templates/report.md 交回报告。

5. 让 chief-of-staff 汇总去重，得到一页分诊单，由你决定处理顺序。

运行方式

Claude Code：安装后在对话里直接点名，例如“用 qa-permission-tester 按项目档案跑一遍权限矩阵”，也可以让主对话按 description 自动派发。

Codex、Antigravity 或其他代理：构建后每个角色有一份完整的 Markdown（dist/markdown/<name>.md，已附共用边界）。在项目的 AGENTS.md 里写一句：

需要质量检查时，按 <本仓库路径>/dist/markdown/qa-permission-tester.md 执行，先读项目根目录的 project-profile.md。

自动化辅助工具

仓库内置轻量级调度辅助工具 scripts/runner.py（无第三方依赖）：

1. 按编排生成计划：

   python3 scripts/runner.py plan pre-release --out run-plan.md
   python3 scripts/runner.py plan pre-release --reports ./reports   # 带出上次分诊单的 P0/P1
   

2. 按改动文件智能推荐岗位：

   python3 scripts/runner.py suggest src/auth/guard.ts src/billing/pricing.vue
   git diff --name-only | python3 scripts/runner.py suggest -
   

3. 多岗位报告汇总与分诊：

   python3 scripts/runner.py triage ./reports --out triage-summary.md
   python3 scripts/runner.py triage ./reports --archive ./reports   # 写为 triage-YYYYMMDD.md，同日不覆盖
   

开源工具与系统生态

部分角色可以搭配本机命令行工具取得第一手证据，多数角色一个，并标明数据是否出本机，详见 可选开源工具：Gitleaks、Semgrep、Playwright、axe-core、Lighthouse、Vale、ScanCode Toolkit。

编排

按场景组合岗位，见 playbooks/：

安全边界

所有角色共用的边界在 roles/_shared.md，构建时附到每个角色末尾：

• 只读优先；只使用项目档案里的测试账号和测试租户。
• 不提审、不发布、不发消息、不付费、不改价、不删数据、不改真实客户配置。
• 生产数据只做聚合，不输出个人信息；示例一律使用虚构数据。
• 每条结论附证据；模拟用户得出的判断只算待验证假设。
• 遇到需要人扫码、登录或批准的步骤就停下交回。

目录

roles/<部门>/<角色>.md      角色卡源文件（唯一正文）
roles/_shared.md            全体角色共用边界
playbooks/                  运行编排
templates/report.md         岗位报告模板（P0 至 P3 分级）
templates/run-plan.md       一次运行的计划模板
project-profile.template.md 项目档案模板
docs/ecosystem.md           可选开源工具
scripts/build.py            生成 dist/
scripts/runner.py           自动化编排与派工辅助工具
scripts/check.py            校验角色卡、编排、禁词与链接
tests/test_build.py         构建与校验的测试

角色卡格式

文件头是简单的 key: value，不依赖 yaml 库：name（全仓唯一的小写连字符）、title、dept、description（写清什么时候该派它）、tools、model、cadence、inputs、outputs、handoff。正文固定八节：使命、什么时候派、开工先读、工作步骤、必查清单、不做的事、交付、交接给谁。每张卡 60 至 150 行。

开发

只用 Python 标准库，无需安装依赖：

python3 scripts/check.py
python3 -m unittest discover -s tests
python3 scripts/build.py

借鉴来源

• gstack：把软件团队的岗位做成可点名的技能，每个岗位有固定的流程与产出。
• contains-studio/agents：按部门组织的子代理集合，以及“什么时候该派它”的描述写法。
• Midscene.js：用自然语言驱动界面操作与验证的思路，用于真实界面上的走查。
• UXAgent：用模拟用户做可用性测试的方法，以及它只能产生待验证假设的局限。

联系与合作

想让角色团适配你的项目，或需要一对一搭建，欢迎在 X 私信：@Fandral2008。

许可

MIT，见 LICENSE。