convez.ai
AgenteAutomaçãoAvançado
astroicers

AI-SOP-Protocol (ASP)

astroicers/AI-SOP-Protocol

Converte padrões dev em constraints executáveis — TDD, ADR, gates automáticos

Ver no GitHub
BomPluginScore · de 0 a 100

Sistema que codifica normas de desenvolvimento em restrições legíveis por máquina, permitindo que Claude automaticamente cumpra TDD, ADR, gates de commit e verificações de release. Elimina a necessidade de repetir instruções a cada sessão novo, integrando-se aos hooks do Git e profiles do Claude.

Instalação

$npx convez-ai astroicers/AI-SOP-Protocol

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
3
Forks
1
Acompanhando
0
Saúde
85%
Último commit
há 2 meses
Versão
v5.1.0
Issues abertas
12
Contribuidores
2

Casos de uso

  • Forçar TDD com gates G1-G4 antes de implementação
  • Bloquear commits em ADR draft e validar arquitetura antes de código
  • Automatizar verificação de segurança (senhas, secrets) antes de deploy
  • Manter histórico de decisões arquiteturais com ADR versionado
  • Executar auditorias de saúde em 9 dimensões do projeto

Veredito

Solução robusta e bem-estruturada para equipes que precisam garantir conformidade com processos dev complexos (TDD, ADR, release gates). Exige investimento inicial em setup e compreensão de máquina de estados, mas compensa em automação e redução de ciclos de revisão. Recomendado para projetos medium-to-large com requerimentos rigorosos.

README

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

AI-SOP-Protocol (ASP)

把開發規範寫成機器可讀的約束,讓 Claude 自動遵守——不用每次提醒「記得寫測試」「先建 ADR」「不要亂推版」。

v5.0.0 · CHANGELOG · 架構文件 · 入門指引 · 授權 MIT


它解決什麼問題

你每次開新 session,Claude 都忘記你的開發規範。ASP 把規範固化成 hooks + profiles + skills,session 啟動時自動載入,無需重複交代。

沒有 ASP有 ASP
每次提醒「先寫測試」G3 Gate 強制:測試先 FAIL 才能實作
ADR 說好不實作,AI 還是動了Draft ADR → git commit 動態阻擋
推版前忘記掃密碼/asp-ship 10 步驟含敏感資訊掃描
不知道 AI 改了什麼範圍SPEC Done When 是二元驗收條件

安裝

ASP 分兩層:User-level(所有專案共用,裝一次)和 Project-level(每個專案的設定,輕量)。

Step 1 — User-level 核心(每台電腦一次)

macOS / Linux / WSL2

bash <(curl -fsSL https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/install.sh)

macOS:系統預設 bash 3.2 不符,請先 brew install bash。

Windows(PowerShell)

irm https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/install.ps1 | iex

需要 Git for Windows、Python 3.10+、jq 1.6+。詳見 docs/install-windows.md。

安裝後:~/.claude/asp/(profiles/hooks)和 ~/.claude/skills/asp/(24 個 skills)即可用於所有專案。

Step 2 — Project-level 設定(每個專案一次,在專案根目錄執行)

bash <(curl -fsSL https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/install.sh)

同一支腳本,第二次在專案目錄跑時,會偵測已有 user-level 並只執行 Phase 2:建立 .ai_profile、CLAUDE.md、.claude/settings.json(hooks 設定)。

安裝腳本會問兩題:專案類型(system / content / architecture)→ 成熟度等級(loose / standard / autonomous,v5 三級制)。全按 Enter 用預設值。


啟動

# 在 Claude Code session 開始時貼這一行:
# 「請讀取 CLAUDE.md,依照 .ai_profile 載入對應 Profile,後續遵循 ASP 協議。」

AI 回覆會列出已載入的 Profile 名稱,和當前 session 的 BLOCKER / WARNING。


預設行為(AI 自動執行,不用記)

時機AI 做的事
Session 啟動讀 .asp-session-briefing.json,報告 BLOCKER;回報 Task Inbox 待授權任務(held,不自動注入;ADR-012/SPEC-007)
跨模組變更先建 ADR;Draft 狀態下 git commit 被動態阻擋
寫測試前/asp-gate G1,G2;寫完跑 G3;實作完跑 G4
Commit 前/asp-ship 十步驟(測試、文件、敏感資訊掃描)
Autopilot 完成自動建 asp/TASK-* branch + Draft PR,等待人工 merge
第三方 API / 版本查證並記錄至 .asp-fact-check.md(global_core.md 自動觸發)
發布版本/asp-release:自動判斷 semver bump、更新 CHANGELOG、建 Draft Release PR

專案設定(.ai_profile)

安裝自動建立,要改行為時編輯它,開新 session 生效。

type: system        # system | content | architecture
level: loose        # loose | standard | autonomous(v5;遺留 0-5 自動映射)
mode: auto          # auto(推薦) | single | multi-agent
hitl: standard      # minimal | standard | strict
autopilot: disabled # enabled 時讀 ROADMAP.yaml 自動執行

完整欄位:~/.claude/asp/templates/example-profile-full.yaml


常用指令

make adr-new TITLE="..."      # 新增架構決策記錄(ADR)
make spec-new TITLE="..."     # 新增功能規格(SPEC)
make audit-health             # 9 維度健康審計
make audit-quick              # 只看 blocker(快速)
make daily-audit              # 產生每日健康日報 .asp-daily-report.md
make ci-install               # 複製 GitHub Actions CI 模板至 .github/workflows/
make asp-unlock-commit        # 解除 Draft ADR 動態 commit 阻擋
make asp-update               # 更新 ASP 核心到最新版
make help                     # 顯示全部指令

不確定該下什麼指令?→ docs/where-to-start.md(場景決策樹)

專案沒有 make:直接請 Claude 執行 /asp-audit,自動 fallback 到 ~/.claude/asp/scripts/audit-fallback.sh。


ADR 狀態機

ASP 用三個狀態管理架構決策的生命週期:

狀態誰可設定允許行為
DraftAI 建立時自動設定禁止生產代碼;git commit 動態阻擋
FIRM人類(需填 Verification Evidence)允許 commit;audit-health 輸出 🟡
Accepted人類完全放行

鐵則(不可被任何設定覆蓋)

  • git push origin main / --force / rebase / rm -rf / docker push / gh pr merge 必須人類確認;feature/* 或 asp/* 由 autopilot 自動推送
  • 禁止輸出 API Key / 密碼 / 憑證
  • ADR Draft 狀態下禁止實作(commit 動態阻擋)
  • 涉及第三方 API / 版本 / 法規 → 必須查證,記錄至 .asp-fact-check.md

完整 7 條:CLAUDE.md


更新 ASP

這台電腦(有 repo)

cd ~/AI-SOP-Protocol
git pull
make asp-update

其他電腦(全新安裝)

重新執行 Step 1 安裝指令,腳本自動覆蓋舊版並 clone repo 到 ~/AI-SOP-Protocol/。

內容更新時
~/.claude/asp/、~/.claude/skills/asp/✅ 覆蓋
~/.claude/CLAUDE.md(ASP 版本)✅ 更新
.ai_profile、docs/adr/、docs/specs/❌ 不動

功能矩陣(v5:Core / Experimental / Showcase,ADR-017)

分類內容安裝方式
Core(daily-driver)hooks(session-audit + 動態 deny)、15 個 asp-* skills、gates G1-G6、12 個 profiles、asp-compile、orchestrator 確定性腳本、levels(loose/standard/autonomous)install.sh 預設
Experimental(凍結)multi-agent worktree 並行(8 腳本 + 10 角色 + 3 skills + Part G profile + SPEC-004 測試)不安裝;見 experimental/multi-agent/(解凍條件 + 手動啟用)
Showcase(展示/研究)telemetry、RAG(本地向量知識庫)、ai-performance 月度回顧install.sh --with-showcase;見 showcase/

深入了解

主題位置
不確定下什麼指令(場景決策樹)docs/where-to-start.md
MVP / 大型功能 / 事故應急docs/runbooks/
成熟度等級(v5 三級制)~/.claude/asp/levels/{loose,standard,autonomous}.yaml
Multi-Agent worktree 隔離(Experimental,v5 凍結)docs/specs/SPEC-004-multi-agent-worktree-isolation.md
Autopilot(ROADMAP 驅動)docs/autopilot.md
架構總覽(含序列圖)docs/architecture.md
Task Inbox schema.asp/templates/task-inbox-schema.json
CI 模板設定.asp/templates/cron-setup.md

移除

# macOS / Linux — 當前專案
bash <(curl -fsSL https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/uninstall.sh)
# macOS / Linux — user-level
bash <(curl -fsSL https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/uninstall.sh) --user-level

# Windows
irm https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/uninstall.ps1 | iex
$env:ASP_USER_LEVEL='1'; irm https://raw.githubusercontent.com/astroicers/AI-SOP-Protocol/main/.asp/scripts/uninstall.ps1 | iex

移除保留 .ai_profile、docs/adr/、docs/specs/ 等你自己撰寫的內容。

Ver o original no GitHub

Bom para

Relacionados