convez.ai
SkillAutomaçãoIntermediário
kross88

AITeamOps - Framework de Colaboração para Times de IA

kross88/AITeamOps

Skill framework que sincroniza múltiplos AIs em projetos com regras, processos e memória

Ver no GitHub
InicialPluginScore · de 0 a 100

Framework unificado que padroniza comportamento de assistentes IA (Claude, ChatGPT, Cursor, Gemini) em projetos de equipe através de Skills reutilizáveis, gestão de memória do projeto e fluxos de trabalho com guardrails. Define regras, rotas e processos em AGENTS.md, Skills e docs para evitar desvios operacionais.

Instalação

$npx convez-ai kross88/AITeamOps

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 3 meses
Versão
v0.1.0
Issues abertas
0
Contribuidores
1

Casos de uso

  • Padronizar comportamento de assistentes IA em equipes de desenvolvimento
  • Criar fluxos automáticos de segurança para commit e deployment
  • Documentar e preservar conhecimento de projeto entre sessões de IA
  • Implementar guardrails operacionais (quando parar, quando pedir confirmação)

Veredito

Abordagem pragmática para governança de IA em times, focando na camada de Skills reutilizáveis. Solução madura para orquestração multi-agente com ênfase em regras explícitas e separação de responsabilidades (AGENTS.md → routing, Skills → execução, docs → fatos de negócio).

README

A tradução para o português deste README ainda está na fila.

AITeamOps

一套面向团队的 AI 协作开发 Skills 集合,让 Claude、Codex、Cursor、ChatGPT 在同一个项目里行为一致、流程可复用、操作有红线。

AITeamOps 把团队在真实项目里反复用到的 AI 操作沉淀成可触发的 Skill:环境初始化、安全提交、数据库只读探测……每个 Skill 都是一份带触发条件的 SKILL.md,AI 工具读到匹配场景就自动按既定流程执行,而不是每次现场即兴发挥。


核心理念

团队协作里,AI 工具最容易出问题的不是「不会写代码」,而是「不知道什么时候该停、该问、该按规矩来」。AITeamOps 用三层分工解决这个问题:

AGENTS.md  →  管「规则」和「路由」:在哪个目录该守什么约束、该读哪个 Skill
Skills     →  管「执行流程」:把可复用的操作步骤固化成可触发的流程
docs       →  管「业务事实」和「验收依据」:业务流程、交接记录、验收清单

三者职责不重叠:规则不写进 Skill,业务事实不写进 AGENTS.md。 本仓库聚焦中间这一层 —— Skills。


包含的 Skills

Skill触发场景一句话作用
team-ai-workspace-bootstrap新项目接入 AI 规范、统一 AGENTS.md、搭 skills/docs 骨架生成目录骨架与 AGENTS.md、docs 模板,统一团队 AI 协作环境
git-commit-guard「帮我提交代码」「commit 一下」「提交并推送」提交前跑检查关卡(diff 审查 → 构建 → 测试),全绿才 commit,push 需显式确认
ai-handoff-doc-update任务完成后「沉淀一下」「更新文档/AGENTS.md」「写交接记录」把本次产出按类别路由到 docs/ai-memory,只在稳定索引变化时才精修 AGENTS.md,不堆任务流水
mysql-readonly-probe-via-java机器无 mysql 客户端、需确认库结构/数据用 JDK + 现成 connector jar 做 MySQL 只读探测,绝不写库

每个 Skill 都内置「红线」与「认知边界」,明确什么动作必须停下来交回给人(push、写库、改业务逻辑等)。


目录结构

AITeamOps/
├── README.md
├── .gitignore
├── scripts/
│   └── install-windows.ps1                          # Windows 下初始化协作目录骨架
└── .agents/
    └── skills/
        ├── team-ai-workspace-bootstrap/SKILL.md     # 环境初始化
        ├── git-commit-guard/SKILL.md                # 安全提交关卡
        ├── ai-handoff-doc-update/SKILL.md           # 任务后文档沉淀
        └── mysql-readonly-probe-via-java/SKILL.md   # 数据库只读探测

安装

Skill 的本质是一个放在约定目录下的 SKILL.md 文件夹,AI 工具启动时扫描该目录即可加载。把本仓库的 Skill 复制到目标位置即可:

用户级(对所有项目生效)

# Claude Code / 通用 agents 约定目录
git clone https://github.com/kross88/AITeamOps.git
cp -r AITeamOps/.agents/skills/* ~/.agents/skills/
# Windows PowerShell
git clone https://github.com/kross88/AITeamOps.git
Copy-Item AITeamOps\.agents\skills\* "$env:USERPROFILE\.agents\skills\" -Recurse

项目级(只对当前项目生效,推荐团队共享时用)

把需要的 Skill 目录放进项目的 .agents/skills/ 下,随仓库一起提交,团队成员拉代码即获得同一套 Skill。

不同工具的 Skill 扫描目录可能不同(如 ~/.claude/skills、项目 .agents/skills)。以你所用工具的文档为准,把对应 SKILL.md 文件夹放进去即可。


怎么触发

Skill 不需要手动调用 —— AI 工具会读取每个 SKILL.md 头部的 description,当你说的话匹配到触发场景时自动加载并按流程执行。例如:

  • 「帮我把这次改动提交了」 → 命中 git-commit-guard,先跑检查关卡再 commit
  • 「这个新项目接入一下 AI 开发规范」 → 命中 team-ai-workspace-bootstrap
  • 「线上这台机器没装 mysql,帮我看下这张表结构」 → 命中 mysql-readonly-probe-via-java

所以 description 写得越准,触发越精确。


让「任务后文档沉淀」每次都触发

ai-handoff-doc-update 的目标是「每次完成任务都沉淀项目记忆」。但要明确一个边界:Skill 是靠 description 匹配的自愿触发,不是 100% 强制。 想让它稳定执行,有两种做法,多数团队用规则驱动即可:

1. 规则驱动(默认推荐,贴合 AGENTS.md 体系)

在项目 AGENTS.md(或团队全局规则)加一条硬约束,把「触发」从 AI 自觉变成明文规则:

## 任务收尾规则
- 完成涉及代码 / SQL / 接口 / 命令的实质改动后,必须调用 `ai-handoff-doc-update` 沉淀文档。
- 沉淀顺序:先更新文档,再用 `git-commit-guard` 提交,让代码与项目记忆进同一个 commit。

优点:贴合现有规则体系、可读、零额外配置。局限:仍依赖 AI 遵守规则,非硬性强制。

2. Hook 强制(harness 执行,硬保证,按需选用)

在 AI 工具的配置(如 Claude Code 的 settings.json)里加一个 Stop hook,每次回复结束由 harness 注入提醒,强制 AI 检查是否需要沉淀。

优点:真正「每次都触发」。局限要权衡清楚:

  • 较"吵":它在每次回复结束都触发一次,无法智能区分「刚完成真任务」和「只是答了个问题」,纯问答也会被拦一下,需要靠 Skill 正文「触发时机」一节来过滤。实测在问答多的会话里会明显拖节奏,多数团队不需要上到这一层。
  • 中文 Windows 编码坑:PowerShell 5.1 默认 stdout 为 GBK,注入的中文会乱码。脚本必须①文件带 UTF-8 BOM(否则 PS 5.1 按 GBK 读源码、中文字符串解析失败),②用 [Console]::OpenStandardOutput() 写原始 UTF-8 字节而非 Write-Output(否则注入文本乱码)。

不同工具的 hook 机制不同,且修改配置文件属于环境变更,请按自己工具的文档手动配置,或在明确授权后让 AI 代为修改。若只是想让团队稳定沉淀文档,优先用「规则驱动」,hook 留给确有硬性要求的场景。


SKILL.md 是怎么工作的

每个 Skill 是一个文件夹,至少包含一个 SKILL.md,结构为「YAML frontmatter + Markdown 正文」:

---
name: git-commit-guard
description: 当用户说「帮我提交代码」「commit 一下」…时使用。本 Skill 会先检查改动、再构建测试,全绿才 commit。
---

# Git Commit Guard

正文:执行流程、红线、常见坑……
  • name:Skill 唯一标识,与文件夹同名,kebab-case。
  • description:决定「何时触发」。要写清适用场景和不适用场景,这是 AI 选用 Skill 的唯一依据。
  • 正文:决定「触发后怎么做」。建议包含:认知边界、红线、分步流程、反馈格式、常见坑。

写好一个 Skill 的关键,是把「什么时候必须停下来交回给人」写进红线 —— push、写库、改业务逻辑这类不可逆或高风险动作,默认不自动做。


新增一个 Skill

  1. 在 .agents/skills/ 下建一个 kebab-case 命名的文件夹。
  2. 写 SKILL.md:先想清楚触发场景(写进 description),再写执行流程和红线(写进正文)。
  3. 在本 README 的「包含的 Skills」表格里登记一行。
  4. 用 git-commit-guard 的思路提交:先自检 diff,再 commit,push 前确认。

写 Skill 时遵循同一套原则:最小流程、明确边界、不替用户做高风险决定。


路线图(规划中)

以下 Skill 已在 team-ai-workspace-bootstrap 中作为配套规划列出,尚未实现:

business-closed-loop-review     # 业务闭环走查
java-springboot-review          # SpringBoot 代码走查
vue-admin-review                # Vue Admin 前端走查
sql-migration-safety            # SQL 变更安全检查

License

MIT

Ver o original no GitHub

Bom para

Relacionados