arcasilesgroup/ai-engineering

ai-engineering 可将任何代码仓库转变为受治理的 AI 工作区。只需一条命令即可安装质量门禁、安全扫描和风险管理——通过 git hooks 在本地强制执行，从而在代码离开您的计算机之前发现问题。它开箱即支持 Claude Code、GitHub Copilot、Gemini CLI 和 OpenAI Codex。 [安装](#install-recommended) · [快速开始](#quick-start) · [工作原理](#how-it-works-short) · [功能特性](#what-you-get) · [治理根目录](#the-governance-root--ai-engineering) · [命令](#commands-reference) · [AI 提供商](#ai-provider-setup) · [贡献指南](#contributing) ## 安装 (推荐) ``` pip install ai-engineering ``` 或者使用 `uv`： ``` uv pip install ai-engineering ``` 需要 Python 3.11+ 和 Git。 ## 快速开始 ``` cd your-project ai-eng install . # bootstrap governance + git hooks ai-eng doctor # verify everything is operational git commit -m "first governed commit" # quality gates run automatically ``` 安装特定的技术栈和 IDE： ``` ai-eng install . --stack python --ide vscode ``` 安装后的下一次提交即受到治理——格式化、linting 和密钥扫描会自动运行。 ## 工作原理 (简述) ai-engineering 是一个**内容框架**，而非平台。治理层由存储库中的 Markdown、YAML 和 JSON 组成。CLI (`ai-eng`) 负责生命周期操作——安装、更新、诊断 (doctor)、验证——而 git hooks 在每次提交和推送时强制执行质量和安全检查。 ``` your-project/ ├── .ai-engineering/ ← governance root (content-first) │ ├── standards/ ← rules for AI agents and quality gates │ ├── skills/ ← 34 procedural skills AI agents execute │ ├── agents/ ← 7 role-based agent personas │ ├── context/ ← project memory: specs, goals, learnings │ └── state/ ← decisions, risks, audit trail ├── .claude/commands/ ← 37 slash commands (Claude Code) ├── .github/prompts/ ← 37 prompt files (GitHub Copilot) ├── .github/agents/ ← 7 custom agents (GitHub Copilot) ├── AGENTS.md ← instruction file (Gemini CLI / Codex / Copilot) ├── .git/hooks/ ← quality gate hooks (auto-installed) └── ...your code ``` 三个所有权边界可保障您内容的安全： - **框架管理**——标准和基线，通过 `ai-eng update` 更新。默认为试运行。 - **团队管理**——您团队的规则和覆盖设置。永远不会被框架更新覆盖。 - **项目管理**——规格说明、产品目标、经验沉淀。永远不会被覆盖。您的项目记忆始终属于您。 ## 功能特性 - **每次提交时的质量门禁**——`ruff`、`gitleaks`、`semgrep`、`pip-audit`、`pytest` 和 `ty` 会在合适的阶段运行。问题在到达远程仓库之前就会被拦截。 - **无需 CI 的安全扫描**——在每次推送时于本地检测密钥、SAST/OWASP 漏洞和依赖项 CVE。 - **风险接受生命周期**——接受、跟踪和使安全风险过期，并根据严重性设定截止日期（严重：15 天，高：30 天，中：60 天，低：90 天）。每个风险最多续期 2 次。 - **34 项流程技能**——用于提交、PR、调试、重构、代码审查、安全评估、架构审查等的结构化流程。AI agent 会读取并执行它们。 - **7 个基于角色的 agent**——用于 plan、execute、build、scan、release、write 和 observe 的行为契约。每个 agent 都有身份、能力和边界。只有 `ai:build` 拥有代码写入权限。 - **多提供商支持**——相同的治理体系适用于 Claude Code (37 个斜杠命令)、GitHub Copilot (37 个提示文件 + 7 个自定义 agent)、Gemini CLI 和 OpenAI Codex。 - **感知技术栈的强制执行**——针对 Python、.NET 和 Next.js 的定制规则。每个技术栈都有自己的一套 linting、测试和安全工具链。 - **内容完整性验证**——6 个编程类别用于验证治理文件在更新期间保持一致。 - **Doctor 诊断**——一条命令即可检查框架健康状况并自动修复缺失的 hooks 或工具。 - **无风险的框架更新**——`ai-eng update` 预览更改。添加 `--apply` 来写入它们。您的团队和项目内容绝不会被触及。 ## 治理根目录 — `.ai-engineering/` 当您运行 `ai-eng install` 时，仓库中会创建一个 `.ai-engineering/` 目录。这是所有治理行为的唯一事实来源。一切都是内容——Markdown、YAML、JSON——人类和 AI agent 都可读取。 ### Standards (标准) AI agent 和质量门禁遵循的规则和约定。 Standards 采用双层模型。**框架层** (`standards/framework/`) 提供基线——覆盖率阈值、复杂度限制、安全要求。**团队层** (`standards/team/`) 是您添加覆盖配置的地方。您的团队可以将覆盖率阈值从 90% 提高到 95%，添加更严格的 linting 规则，或定义项目特定的约定。框架更新永远不会触及团队层。 每个受支持的技术栈（Python、.NET、Next.js）都有自己的标准文件，其中包含针对 linting、格式化、测试和依赖管理的定制规则。 ### Skills (技能) — 34 项扁平化组织 Skills 是用 Markdown 编写的分步流程，任何 AI agent 都可以读取和执行。它们定义了 agent 做**什么**、**何时**触发、**如何**执行以及输出**什么**。所有 skills 都位于 `skills//SKILL.md` 中——没有嵌套分类。 Skill frontmatter 遵循受治理的 schema，顶层包含 `name` 和 `description`，`metadata` 下包含版本控制/分类（例如：`metadata.version`、`metadata.tags`、`metadata.ai-engineering`）。 | Skills (按字母顺序) | |-----------------------| | a11y, api, architecture, build, changelog, cicd, cleanup, cli, code-simplifier, commit, create, db, debug, delete, discover, docs, explain, feature-gap, governance, infra, migrate, observe, perf, plan, pr, quality, refactor, release, risk, security, spec, standards, test, work-item | 使用 `/ai:` 调用任何 skill——例如，`/ai:debug` 用于系统性诊断，`/ai:security` 用于安全评估，或 `/ai:refactor` 用于代码重构。 Skills 与提供商无关——相同的 skill 可在 Claude Code、GitHub Copilot、Gemini CLI 和 OpenAI Codex 中无需修改即可使用。 ### Agents — 7 个基于角色的人格 Agents 是 AI 的行为契约。每个 agent 都有身份、能力、激活规则、引用的 skills、输出契约和边界。 | Agent | 角色 | 范围 | |-------|------|-------| | **plan** | 规划流水线、规格创建、执行计划——在执行前停止 | 读写 | | **execute** | 读取已批准的计划、调度 agent、协调、检查点、报告 | 读写 | | **build** | 跨所有技术栈的实现（唯一拥有代码写入权限的 agent） | 读写 | | **scan** | 7 模式评估：治理、安全、质量、性能 (perf)、无障碍 (a11y)、功能、架构 | 读写（仅限工作项） | | **release** | ALM 生命周期：commit、PR、发布门禁、分流、work-items、部署 | 读写 | | **write** | 文档（生成/简化模式） | 读写（仅限文档） | | **observe** | 可观测性：4 个受众层级中的 5 种模式 + DORA 指标 + 健康评分 | 只读 | 使用 `/ai:` 激活任何 agent——例如，`/ai:build` 用于实现，或 `/ai:scan` 用于评估。 ### Context (上下文) — 您的项目记忆 Context 是您项目生存的地方。产品目标、活动规格说明、制度化的经验——全部存储为 Markdown 文件，供 AI agent 读取以了解您的项目。 规格驱动交付模型通过四个文档跟踪工作： - **spec.md** ——构建什么（需求、范围、验收标准） - **plan.md** ——如何构建（架构决策、方法、权衡） - **tasks.md** ——做什么（有序、可分配、可跟踪的任务） - **done.md** ——做了什么（完成日志、捕获的经验） 任何 AI agent 都可以通过读取 `_active.md` → `spec.md` → `tasks.md` 来恢复任何规格的工作。会话之间不会丢失任何上下文。 Context 是项目管理的——框架永远不会覆盖它。 ### State (状态) — 决策、风险和审计跟踪 State 文件自动跟踪运行时信息： - **decision-store.json** ——决策通过 SHA-256 上下文哈希在 AI 会话之间持久化。没有重复的问题——agent 在询问之前会先检查存储。 - **audit-log.ndjson** ——每个治理事件的仅追加日志（门禁结果、执行的命令、生命周期转换）。 - **install-manifest.json** ——安装了什么、何时安装、哪个版本。 - **ownership-map.json** ——谁拥有治理根目录中的每个路径。 - **sources.lock.json** ——带有校验和验证的远程 skill 源。 State 是系统管理的——由 CLI 和 git hooks 自动维护。 ## 命令 (参考) 您日常使用的核心命令： ``` ai-eng install [TARGET] # Bootstrap governance in any project ai-eng install --provider claude_code --provider github_copilot # Select AI providers ai-eng update [TARGET] # Preview framework updates (dry-run) ai-eng update [TARGET] --apply # Apply framework updates ai-eng doctor [TARGET] # Diagnose and auto-fix framework health ai-eng guide [TARGET] # View branch policy setup instructions ai-eng validate [TARGET] # Validate content integrity ai-eng spec verify|catalog|list|compact # Spec lifecycle management ai-eng decision record "