AI Friendly Audit（AI 亲和度审计）v3.0

概述

此技能用于系统性评估代码仓库对 AI Coding 工具的友好程度。通过自动化脚本收集数据 + 人工审查相结合，生成量化评分和改进建议报告，帮助团队优化代码仓库以获得更好的 AI 协作体验。

适用范围: 前端、后端、全栈、SDK/库、Monorepo 等各类项目。

v3.0 新增: 融合 OpenAI Harness Engineering 方法论，新增"Outer Loop & 反馈闭环"维度，强调机械化不变量、评估门禁和自验证能力。

核心理念

AI 亲和的代码仓库应具备以下特质：

1. 信任链闭环（Inner Loop） — AI 做出的修改可被快速验证（测试、类型检查、lint），形成"修改→验证→反馈"的快速循环
2. 最小可运行环境 — 降低环境依赖，便于 AI 理解和复现问题，能在本地快速启动和验证
3. 规范驱动开发（SDD） — 文档即规范，AI 可据此生成和验证代码，而不是靠猜测
4. 上下文窗口友好 — 单文件可被完整读取，代码粒度适合 AI 处理，避免"记忆墙"问题
5. 代码自述性 — 文件和函数自带足够上下文，减少 AI 跳转查阅的需要
6. 机械化不变量（Outer Loop） — 架构意图必须通过自动化手段（linter 规则、结构测试、评估门禁）机械化执行，而非仅靠文档约定。参考 OpenAI Harness Engineering："Agent 会按比例复制模式，架构约束必须机械化执行"

Inner Loop 与 Outer Loop

┌──────────────────────────────────────────────────────────────┐
│  Inner Loop（Agent 执行循环）                                 │
│  prompt → 推理 → 工具调用 → 输出 → 再次推理 → ... → 完成    │
└──────────────────────────────────────────────────────────────┘
                              ↕
┌──────────────────────────────────────────────────────────────┐
│  Outer Loop（质量保障闭环）                                   │
│  类型检查 → 单元测试 → 结构测试 → 覆盖率门禁 → 构建验证     │
│  AGENTS.md → 架构文档 → 评估门禁 → 回归检测                  │
└──────────────────────────────────────────────────────────────┘

• Inner Loop: AI Agent 的推理-执行循环，关注单次任务的正确执行
• Outer Loop: 围绕 Agent 构建的质量保障体系，确保 AI 生成的代码持续符合架构规范

审计工作流程

关于"记忆墙"问题

AI Coding 工具的上下文窗口有限。审计过程中，优先使用脚本自动收集数据并输出结构化结果，避免逐个文件手动检查导致上下文溢出。工作流设计为"脚本先行、人工补充"模式。

Phase 1: 自动化扫描（脚本驱动）

运行自动化脚本收集仓库基础数据，这一步会输出结构化的 JSON 数据，覆盖大部分可自动检测的维度：

python3 scripts/repo_scan.py <repo_path> --json

脚本会自动检测并输出：

• 项目类型（前端/后端/全栈/库）和技术栈（语言、框架、包管理器）
• 各维度的自动化检查结果（文件存在性、配置检测等）
• 文件体积统计和评分
• Outer Loop 基础设施检测（结构测试、覆盖率门禁、质量脚本等）

如果只需要检查文件体积：

python3 scripts/check_file_size.py <src_path> --warn 500 --error 1000 --json

Phase 2: 人工补充检查

脚本无法覆盖的维度（如代码质量、错误处理模式、架构合理性等）需要人工抽样检查。参考 references/checklist.md 中标注为"需人工检查"的项目。

人工检查时，聚焦于：

• 抽查 3-5 个核心源文件，评估代码自述性和命名规范
• 查看错误处理模式是否统一
• 评估模块边界是否清晰
• [v3.0] 检查是否存在结构测试（验证分层规则、导入约束等）
• [v3.0] 评估 AGENTS.md 是否为"目录式"结构（~100 行入口 + 独立文档），而非百科全书式

Phase 3: 生成报告

根据脚本输出 + 人工检查结果，使用 references/report_template.md 模板生成最终报告。

---

审计维度（11 个维度）

以下维度适用于所有项目类型。每个维度满分 4 分，通过权重加权计算总分（满分 100）。

#	维度	权重	适用范围	关键检查点
1	最小可运行环境	11%	全部	一键启动、依赖屏蔽/Mock、环境变量模板、依赖锁定
2	类型系统与静态分析	11%	全部	静态类型、严格模式、类型覆盖率
3	测试体系	14%	全部	单元测试、集成/E2E 测试、覆盖率、测试可独立运行
4	文档完备性	10%	全部	README、架构文档、API 文档、开发指南
5	代码规范与自动化	7%	全部	Linting、格式化、Git Hooks、提交规范
6	模块化架构	9%	全部	分层清晰、低耦合、职责单一、无循环依赖
7	上下文窗口友好性	9%	全部	文件行数、函数复杂度、模块粒度
8	代码自述性	7%	全部	文件综述、语义化命名、关键注释
9	AI 工具与 SDD 支持	8%	全部	AI 配置文件、API 规范、架构规范
10	依赖隔离与可复现性	5%	全部	外部依赖可屏蔽、构建可复现、容器化支持
11	Outer Loop & 反馈闭环	9%	全部	结构测试、评估门禁、覆盖率阈值、质量脚本、机械化不变量

v3.0 变化: 新增维度 11，其余维度权重微调以容纳新维度，总权重保持 100%。

---

各维度检查指南

1. 最小可运行环境（11%）

核心目标: AI Coding 工具可在本地快速启动应用并验证修改效果。

不同技术栈的检查重点：

技术栈	一键启动	依赖屏蔽	环境模板	依赖锁定
Node.js	npm run dev	MSW / json-server	.env.example	package-lock.json
Go	make run / go run	接口 Mock / build tags	.env.example	go.sum + vendor
Java/Kotlin	mvn spring-boot:run	Spring Profiles + H2	application-local.properties	pom.xml 版本锁定
Python	python -m app	pytest fixtures / mock	.env.example	requirements.txt / poetry.lock
Rust	cargo run	feature flags / mock traits	.env.example	Cargo.lock

评分标准：

• 4分：一键启动 + 依赖可屏蔽 + 环境模板 + 依赖锁定
• 3分：一键启动 + 有启动文档或部分 Mock
• 2分：可启动但需手动配置
• 1分：启动依赖外部服务，无 Mock 方案
• 0分：无明确启动方式或强依赖外部服务

2. 类型系统与静态分析（11%）

核心目标: 静态类型检查提供快速反馈，AI 生成的代码可被类型系统即时校验。

技术栈	类型系统	严格模式	检查命令
TypeScript	tsconfig.json strict	noImplicitAny 等	npx tsc --noEmit
Go	内置强类型	go vet + staticcheck	go vet ./...
Java/Kotlin	内置强类型	Error-Prone / NullAway	mvn compile
Python	mypy / pyright	strict mode	mypy --strict src/
Rust	内置强类型	#![deny(warnings)]	cargo check

评分标准：

• 4分：强类型 + 严格模式 + 静态分析工具 + 无类型逃逸
• 3分：有类型系统，少量类型逃逸（any / unsafe / suppress）
• 2分：有类型系统但配置宽松
• 1分：部分代码有类型
• 0分：动态语言无类型注解

3. 测试体系（14%）

核心目标: AI 修改代码后可快速运行测试验证正确性，形成信任链闭环。

检查项：

• 测试框架配置: Jest/Vitest、Go testing、JUnit/TestNG、pytest 等
• 测试覆盖率: 配置覆盖率报告工具（Istanbul、JaCoCo、coverage.py 等）
• 测试可独立运行: 不依赖外部服务（数据库、API 等），使用 mock/fixture/testcontainers
• 核心路径覆盖: 关键业务逻辑有测试保护

评分标准：

• 4分：覆盖率 >70% + 核心路径有测试 + 测试可独立运行 + E2E/集成测试
• 3分：覆盖率 50-70% + 有单元测试框架 + 部分 mock
• 2分：有测试但覆盖率低或依赖外部服务
• 1分：有测试框架但测试极少
• 0分：无测试

4. 文档完备性（10%）

核心目标: AI 可通过文档理解项目上下文、架构决策和开发规范。

必查文档：

• README.md — 项目简介、快速开始、项目结构
• 架构文档 — 系统架构、模块关系、数据流（如 docs/architecture.md）
• API 文档 — 接口定义、请求/响应格式（OpenAPI spec 或 Markdown）
• 开发规范 — 编码规范、目录约定、命名规则（如 backend_dev_rule.md）

[v3.0] AGENTS.md 最佳实践 (参考 OpenAI Harness Engineering):

• AGENTS.md 应为目录式结构（~100 行入口），而非百科全书
• 详细规范应分散到独立文档（.cursor/rules/、docs/ 等）
• 避免在 AGENTS.md 中堆砌过多内容，防止挤占 Agent 的任务上下文

评分标准：

• 4分：README + 架构文档 + API 文档 + 开发规范 + AI 指南
• 3分：README 完整 + 架构文档或 API 文档
• 2分：README 基本完整
• 1分：README 简单或过期
• 0分：无文档

5. 代码规范与自动化（7%）

核心目标: 代码风格一致，AI 生成代码可被自动校验和格式化。

技术栈	Linting	格式化	Git Hooks
TypeScript	ESLint / Biome	Prettier	husky + lint-staged
Go	golangci-lint	gofmt / goimports	pre-commit
Java	Checkstyle / Error-Prone	google-java-format	pre-commit
Python	ruff / pylint	black / ruff format	pre-commit
Rust	clippy	rustfmt	pre-commit

评分标准：

• 4分：Lint + Format + Pre-commit + 提交规范
• 3分：Lint + Format + Pre-commit
• 2分：Lint + Format
• 1分：仅有 Lint 配置
• 0分：无规范约束

6. 模块化架构（9%）

核心目标: 代码结构清晰，AI 可理解边界并进行局部修改而不影响全局。

不同项目类型的模块化标准：

项目类型	良好结构	差的结构
前端	按功能/页面组织，组件/hooks/services 分离	所有组件平铺在一个目录
Go 后端	cmd/ + pkg/ 或 internal/，按领域划分包	所有代码在一个 package
Java 后端	controller → service → dao 分层，按模块划分包	所有类在一个包里
Python 后端	按模块划分，清晰的 __init__.py 导出	单个巨大的 app.py

评分标准：

• 4分：清晰分层 + 无循环依赖 + 职责单一 + 模块边界清晰
• 3分：合理分层，少量耦合
• 2分：有分层但边界模糊
• 1分：耦合较重，修改一处需要改多处
• 0分：意大利面代码

7. 上下文窗口友好性（9%）

核心目标: 确保代码文件可被 AI 完整读取和理解，避免因文件过长导致上下文截断。

使用脚本检查：

python3 scripts/check_file_size.py <src_path> --warn 500 --error 1000

行数阈值建议:

类型	推荐	警告	严重
源文件	≤500 行	500-1000 行	>1000 行
函数/方法	≤80 行	80-150 行	>150 行
类/组件	≤300 行	300-600 行	>600 行
测试文件	≤800 行	800-1500 行	>1500 行

评分标准：

• 4分：90% 文件 ≤500 行 + 无超过 1000 行的文件
• 3分：80% 文件 ≤500 行 + 少量 500-1000 行文件
• 2分：存在多个 500-1000 行文件，少量超过 1000 行
• 1分：多个文件超过 1000 行
• 0分：大量文件超过 1000 行或存在超过 2000 行的巨型文件

8. 代码自述性（7%）

核心目标: AI 无需跳转多个文件就能理解当前代码的目的和上下文。

检查要点：

• 文件综述: 文件开头有注释说明职责（Go 的 package doc、Java 的 class Javadoc、Python 的 module docstring）
• 函数文档: 公开函数/方法有文档注释说明参数、返回值和用途
• 语义化命名: 变量、函数、文件名具有描述性，避免缩写和单字母
• 关键逻辑注释: 复杂算法或业务逻辑有解释性注释

评分标准：

• 4分：90% 文件有综述 + 公开 API 有完整文档 + 语义化命名一致
• 3分：核心文件有综述 + 主要函数有文档
• 2分：部分文件有注释，命名基本规范
• 1分：注释稀少，命名不规范
• 0分：无注释，命名混乱

9. AI 工具与 SDD 支持（8%）

核心目标: 项目有 AI 工具配置和规范驱动开发支持，AI 可据此理解项目意图。

检查项：

类别	文件/工具	说明
AI 配置	.cursorrules / .cursor/rules/	Cursor AI 编码规则
AI 配置	AGENTS.md	Claude Code 指南
AI 配置	.github/copilot-instructions.md	Copilot 指令
AI 上下文	Memory Bank / .lingma/	AI 助手项目上下文
API 规范	openapi.yaml / Swagger	机器可读的 API 定义
开发规范	CONVENTIONS.md / *_dev_rule.md	编码规范文档
架构规范	Architecture.md / 设计文档	架构决策记录
AI 技能	.cursor/skills/ / .claude/skills/	可复用的 AI 操作规范

[v3.0] 机械化不变量 (参考 OpenAI Harness Engineering):

• 架构约束不能仅靠文档 — 必须有自动化手段执行
• 检查是否有自定义 linter 规则或结构测试验证分层/导入约束
• 示例：禁止 pages/ 直接导入底层模块、验证 Tailwind 版本合规性

评分标准：

• 4分：AI 配置 + API 规范 + 开发规范 + 架构文档 + 机械化约束
• 3分：有 AI 配置 + 架构文档或 API 规范
• 2分：有架构文档或 AI 配置文件
• 1分：仅有基本 README
• 0分：无任何规范驱动文档

10. 依赖隔离与可复现性（5%）

核心目标: 外部依赖可被屏蔽或替换，构建结果可复现。

技术栈	依赖隔离方式	构建可复现	容器化
Node.js	MSW / mock service	lock 文件 + .nvmrc	Dockerfile
Go	interface mock / build tags	go.sum + vendor	Dockerfile
Java	Spring Profiles + H2/Testcontainers	Maven wrapper + 版本锁定	Dockerfile
Python	pytest mock / dependency injection	poetry.lock / pip freeze	Dockerfile

评分标准：

• 4分：外部依赖全部可屏蔽 + 构建可复现 + 有容器化
• 3分：主要依赖可屏蔽 + 构建可复现
• 2分：部分依赖可屏蔽
• 1分：强依赖外部服务，但有文档说明
• 0分：强依赖外部服务，无隔离方案

11. Outer Loop & 反馈闭环（9%）🆕

核心目标: 围绕 AI Agent 构建完整的质量保障闭环，确保 AI 生成的代码持续符合架构规范。

参考 OpenAI Harness Engineering: "人的角色从写代码变为设计环境——让 Agent 可靠地产出正确的代码。" 关键洞察："架构意图必须通过自定义 linter 和结构测试机械化执行，因为 Agent 会按比例复制模式。"

检查项：

类别	检查点	示例
结构测试	是否有架构约束的自动化测试	分层导入规则、文件体积上限、JSDoc 覆盖率
评估门禁	是否有一键质量脚本	ai:check、quality_check.sh
覆盖率阈值	测试覆盖率是否有阈值门禁	vitest coverage thresholds、jacoco minimums
回归检测	是否可检测质量趋势变化	IHS 报告、SonarQube、自定义趋势脚本
可观测性	Agent 是否可访问日志/错误来自我验证	结构化日志、错误追踪集成

各技术栈的 Outer Loop 实践：

技术栈	结构测试	评估门禁	回归检测
TypeScript	architecture.test.ts（导入约束、体积检查）	npm run ai:check	IHS 报告 / 覆盖率趋势
Go	go test 包导入约束测试	make check / golangci-lint	覆盖率趋势
Java	ArchUnit 测试（分层约束）	mvn verify	JaCoCo 报告
Python	pytest 导入约束测试	tox / nox	覆盖率趋势

评分标准：

• 4分：结构测试 + 一键评估门禁 + 覆盖率阈值 + 回归检测
• 3分：一键评估门禁 + 覆盖率阈值
• 2分：有部分评估脚本
• 1分：仅有 CI 基础构建
• 0分：无任何质量保障闭环

---

评分等级

等级	分数范围	描述
A	90-100	AI 亲和度优秀，可高效协作
B	75-89	AI 亲和度良好，有小幅改进空间
C	60-74	AI 亲和度一般，需重点改进
D	40-59	AI 亲和度较差，需系统性改造
F	<40	AI 亲和度极低，不适合 AI 协作

---

改进建议模板

报告中的改进建议应按技术栈给出具体可操作的步骤。以下是各类项目常见的改进方向：

后端项目常见改进

1. 添加 API 文档 — 为 REST/gRPC 接口生成 OpenAPI spec 或编写接口文档
2. 拆分大文件 — 将超过 1000 行的文件按职责拆分（如 Go 的 scheduler.go 拆为 filter.go、priority.go、scorer.go）
3. 添加本地开发配置 — 提供 .env.example、application-local.properties、docker-compose.dev.yml 等
4. 配置静态分析 — Go 项目添加 .golangci.yml，Java 项目配置 Error-Prone/Checkstyle
5. 编写架构文档 — 说明模块关系、数据流、关键设计决策
6. 添加 AI 配置文件 — 创建 .cursorrules 或 AGENTS.md 指导 AI 行为
7. [v3.0] 添加结构测试 — 使用 ArchUnit (Java) 或自定义测试验证分层约束

前端项目常见改进

1. 配置 Mock 模式 — 使用 MSW 或 json-server 屏蔽后端依赖
2. 启用 TypeScript strict — 开启严格模式，消除 any 类型
3. 添加组件文档 — Storybook 或组件级注释
4. 配置 E2E 测试 — Playwright/Cypress 覆盖关键流程
5. [v3.0] 添加架构约束测试 — 验证导入方向、Tailwind 版本合规、文件体积上限

通用改进

1. 创建 .cursorrules — 定义编码规范和 AI 协作指南
2. 为核心文件添加文件综述 — 文件开头说明职责和依赖
3. 运行 check_file_size.py — 定期检查并拆分超标文件
4. 编写开发规范文档 — 明确目录约定、命名规则、错误处理模式
5. [v3.0] 构建 Outer Loop — 添加一键质量脚本、覆盖率阈值、结构测试

Outer Loop 建设路线图（v3.0 新增）

阶段	目标	关键动作
L1 基础	可运行 + 可检查	ai:check 脚本、lint + type-check
L2 门禁	覆盖率不退化	覆盖率阈值、pre-commit hooks
L3 约束	架构机械化	结构测试、自定义 linter 规则
L4 闭环	趋势可追踪	IHS/SonarQube 报告、回归检测
L5 自治	Agent 可自验证	Agent 可访问日志/错误、自修复循环

---

Harness Engineering 参考

以下要点提炼自 OpenAI Harness Engineering 文章 (2026-02)

核心观点

1. 工程师角色转变: 从写代码变为设计环境——让 Agent 可靠地产出正确的代码
2. 机械化不变量: 架构意图必须通过自定义 linter 和结构测试机械化执行，仅靠文档不够
3. AGENTS.md 作为目录: ~100 行入口，指向独立文档，避免百科全书式导致上下文挤占
4. 可观测性即自验证: Agent 应能访问日志、指标、追踪来自我验证和修复
5. 评估门禁: 结构化的"完成"标准（回归测试、安全检查），让 Agent 可自主判断任务完成
6. 人的注意力是稀缺资源: 系统设计应最大化 Agent 的自主性，最小化人工审查负担

适用于审计的关键指标

指标	低成熟度	高成熟度
架构约束	仅文档描述	结构测试 + 自定义 linter 机械化执行
质量门禁	无或仅 CI 构建	一键脚本 + 覆盖率阈值 + 回归检测
AGENTS.md	无或百科全书式	目录入口 + 独立规范文档
Agent 自验证	无	可访问日志/错误，闭环修复

---

资源文件

scripts/

• repo_scan.py — 自动化仓库扫描脚本，收集基础信息并输出 JSON
• check_file_size.py — 文件体积检查脚本

references/

• checklist.md — 完整的检查清单和评分细则
• report_template.md — 报告输出模板

快速开始

1. 运行 python3 scripts/repo_scan.py <repo_path> --json 获取自动化扫描数据
2. 阅读脚本输出，对照 11 个维度评估
3. 对脚本无法覆盖的维度（错误处理、代码自述性、Outer Loop 成熟度等）进行人工抽样
4. 使用 references/report_template.md 生成报告
5. 按优先级提出改进建议，优先推荐 Quick Wins
6. [v3.0] 特别关注 Outer Loop 建设成熟度，评估是否有结构测试和评估门禁