project-health

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Project Health: AI-Agent Readiness Auditing

项目健康度：AI-Agent就绪性审计

Status: Active Updated: 2026-01-30 Focus: Ensuring documentation and workflows are executable by AI agents

状态：已启用 更新时间：2026-01-30 核心目标：确保文档和工作流可被AI Agent执行

Overview

概述

This skill evaluates project health from an AI-agent perspective - not just whether docs are well-written for humans, but whether future Claude Code sessions can:

Understand the documentation without ambiguity
Execute workflows by following instructions literally
Resume work effectively with proper context handoff

该技能从AI-Agent视角评估项目健康度——不仅关注文档是否适合人类阅读，更着重于未来Claude Code会话能否：

理解文档内容，无歧义
严格遵循指令执行工作流
有效恢复工作，保持上下文连续性

When to Use

使用场景

Before handing off a project to another AI session
When onboarding AI agents to contribute to a codebase
After major refactors to ensure docs are still AI-executable
When workflows fail because agents "didn't understand"
Periodic health checks for AI-maintained projects

将项目交接给其他AI会话前
为代码库引入AI Agent时
重大重构后，确保文档仍可被AI执行
因Agent“无法理解”导致工作流失败时
对AI维护的项目进行定期健康度检查

Agent Selection Guide

Agent选择指南

Situation	Use Agent	Why
"Will another Claude session understand this?"	context-auditor	Checks for ambiguous references, implicit knowledge, incomplete examples
"Will this workflow actually execute?"	workflow-validator	Verifies steps are discrete, ordered, and include verification
"Can a new session pick up where I left off?"	handoff-checker	Validates SESSION.md, phase tracking, context preservation
Full project health audit	All three	Comprehensive AI-readiness assessment

场景	使用Agent	原因
“其他Claude会话能理解这些内容吗？”	context-auditor	检查模糊引用、隐含知识、不完整示例
“这个工作流真的能执行吗？”	workflow-validator	验证步骤是否独立、有序且包含验证环节
“新会话能接续我当前的工作吗？”	handoff-checker	验证SESSION.md、阶段跟踪、上下文保存情况
完整项目健康度审计	全部三个	全面的AI就绪性评估

Key Principles

核心原则

1. Literal Interpretation

1. 字面指令遵循

AI agents follow instructions literally. Documentation that works for humans (who fill in gaps) may fail for agents.

Human-friendly (ambiguous):

"Update the config file with your settings"

AI-friendly (explicit):

"Edit
wrangler.jsonc
and set
account_id
to your Cloudflare account ID (find it at dash.cloudflare.com → Overview → Account ID)"

AI Agent会严格按照字面意思执行指令。适合人类阅读的文档（人类会自行填补信息空白）可能无法被Agent正确执行。

人类友好型（存在歧义）：

"用你的设置更新配置文件"

AI友好型（明确无歧义）：

"编辑
wrangler.jsonc
，将
account_id
设置为你的Cloudflare账户ID（可在dash.cloudflare.com → 概览 → 账户ID中找到）"

2. Explicit Over Implicit

2. 明确优先于隐含

Never assume the agent knows:

Which file you mean
What "obvious" next steps are
Environment state or prerequisites
What success looks like

永远不要假设Agent知道：

你指的是哪个文件
“显而易见”的下一步是什么
环境状态或前置条件
成功的标准是什么

3. Verification at Every Step

3. 每步都需验证

Agents can't tell if something "feels right". Include verification:

Expected output after each command
How to check if a step succeeded
What to do if it failed

Agent无法判断结果“是否合理”。需包含验证环节：

每个命令执行后的预期输出
如何检查步骤是否成功
失败后的处理方式

Agents

Agent详情

context-auditor

Purpose: Evaluate AI-readability of documentation

Checks:

Instructions use imperative verbs (actionable)
File paths are explicit (not "the config file")
Success criteria are measurable
No ambiguous references ("that thing", "as discussed")
Code examples are complete (not fragments)
Dependencies/prerequisites stated explicitly
Error handling documented

Output: AI-Readability Score (0-100) with specific issues

用途：评估文档的AI可读性

检查项：

指令使用祈使动词（可执行）
文件路径明确（而非“配置文件”）
成功标准可衡量
无模糊引用（如“那个东西”、“如之前讨论”）
代码示例完整（而非片段）
明确声明依赖/前置条件
文档包含错误处理说明

输出：AI可读性得分（0-100分）及具体问题

workflow-validator

Purpose: Verify processes are executable when followed literally

Checks:

Steps are discrete and ordered
Each step has clear input/output
No implicit knowledge required
Environment assumptions documented
Verification step after each action
Failure modes and recovery documented
No "obvious" steps omitted

Output: Executability Score (0-100) with step-by-step analysis

用途：验证流程被严格执行时的可操作性

检查项：

步骤独立且有序
每个步骤有清晰的输入/输出
无需隐含知识即可执行
文档说明环境假设
每个操作后包含验证步骤
文档说明失败模式及恢复方法
无遗漏“显而易见”的步骤

输出：可执行性得分（0-100分）及分步分析

handoff-checker

Purpose: Ensure session continuity for multi-session work

Checks:

SESSION.md or equivalent exists
Current phase/status clear
Next actions documented
Blockers/decisions needed listed
Context for future sessions preserved
Git checkpoint pattern in use
Architecture decisions documented with rationale

Output: Handoff Quality Score (0-100) with continuity gaps

用途：确保多会话工作的连续性

检查项：

存在SESSION.md或等效文件
当前阶段/状态清晰
文档记录下一步操作
列出阻塞点/需做的决策
为未来会话保留上下文
使用Git checkpoint模式
文档记录架构决策及理由

输出：交接质量得分（0-100分）及连续性缺口

Templates

模板

AI-Readable Documentation Template

AI可读文档模板

See

templates/AI_READABLE_DOC.md

for a template that ensures AI-readability.

Key sections:

Prerequisites (explicit environment/state requirements)
Steps (numbered, discrete, with verification)
Expected Output (what success looks like)
Troubleshooting (common failures and fixes)

请查看

templates/AI_READABLE_DOC.md

，获取确保AI可读性的模板。

核心章节：

前置条件（明确的环境/状态要求）
步骤（编号、独立、包含验证）
预期输出（成功的标准）
故障排除（常见失败及修复方法）

Handoff Checklist

交接检查清单

See

templates/HANDOFF_CHECKLIST.md

for ensuring clean session handoffs.

请查看

templates/HANDOFF_CHECKLIST.md

，确保会话交接顺畅。

Anti-Patterns

反模式

1. "See Above" References

1. “参见上文”引用

markdown

undefined

markdown

undefined

Bad

不良示例

As mentioned above, configure the database.

如上文所述，配置数据库。

Good

良好示例

Configure the database by running:

npx wrangler d1 create my-db

undefined

通过运行以下命令配置数据库：

npx wrangler d1 create my-db

undefined

2. Implicit File Paths

2. 隐含文件路径

markdown

undefined

markdown

undefined

Bad

不良示例

Update the config with your API key.

用你的API密钥更新配置。

Good

良好示例

Add your API key to

.dev.vars

API_KEY=your-key-here

undefined

将你的API密钥添加到

.dev.vars

：

API_KEY=your-key-here

undefined

3. Missing Verification

3. 缺少验证环节

markdown

undefined

markdown

undefined

Bad

不良示例

Run the migration.

运行迁移。

Good

良好示例

Run the migration:

npx wrangler d1 migrations apply my-db --local

Verify with:

npx wrangler d1 execute my-db --local --command "SELECT name FROM sqlite_master WHERE type='table'"

Expected output: Should show your table names.

undefined

运行迁移：

npx wrangler d1 migrations apply my-db --local

验证命令：

npx wrangler d1 execute my-db --local --command "SELECT name FROM sqlite_master WHERE type='table'"

预期输出：应显示你的表名。

undefined

4. Assumed Context

4. 假设已有上下文

markdown

undefined

markdown

undefined

Bad

不良示例

Now deploy (you know the drill).

现在部署（你懂的）。

Good

良好示例

Deploy to production:

npx wrangler deploy

Verify deployment at: https://your-worker.your-subdomain.workers.dev

undefined

部署到生产环境：

npx wrangler deploy

在以下地址验证部署：https://your-worker.your-subdomain.workers.dev

undefined

Relationship to Other Tools

与其他工具的关系

Tool	Focus	Audience
`project-docs-auditor`	Traditional doc quality (links, freshness, structure)	Human readers
`project-health` skill	AI-agent readiness (executability, clarity, handoff)	Claude sessions
`docs-workflow` skill	Creating/managing specific doc files	Both

工具	核心焦点	受众
`project-docs-auditor`	传统文档质量（链接、时效性、结构）	人类读者
`project-health` 技能	AI-Agent就绪性（可执行性、清晰度、交接）	Claude会话
`docs-workflow` 技能	创建/管理特定文档文件	两者兼顾

Quick Start

快速开始

Full audit: "Run all project-health agents on this repo"
Check one aspect: "Use context-auditor to check AI-readability"
Before handoff: "Use handoff-checker before I end this session"

完整审计：“在本仓库运行所有project-health Agent”
单维度检查：“使用context-auditor检查AI可读性”
交接前检查：“在我结束会话前使用handoff-checker”

Success Metrics

成功指标

A healthy project scores:

Context Auditor: 80+ (AI can understand without clarification)
Workflow Validator: 90+ (steps execute literally without failure)
Handoff Checker: 85+ (new session can resume immediately)

Projects below these thresholds have documentation debt that will slow future AI sessions.

健康的项目需达到以下分数：

Context Auditor：80分以上（AI无需澄清即可理解）
Workflow Validator：90分以上（步骤可被严格执行且无失败）
Handoff Checker：85分以上（新会话可立即接续工作）

低于这些阈值的项目存在文档债务，会拖慢未来AI会话的效率。