Back to Details

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:
  1. Understand the documentation without ambiguity
  2. Execute workflows by following instructions literally
  3. Resume work effectively with proper context handoff
该技能从AI-Agent视角评估项目健康度——不仅关注文档是否适合人类阅读，更着重于未来Claude Code会话能否：
  1. 理解文档内容，无歧义
  2. 严格遵循指令执行工作流
  3. 有效恢复工作，保持上下文连续性

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选择指南

SituationUse AgentWhy
"Will another Claude session understand this?"context-auditorChecks for ambiguous references, implicit knowledge, incomplete examples
"Will this workflow actually execute?"workflow-validatorVerifies steps are discrete, ordered, and include verification
"Can a new session pick up where I left off?"handoff-checkerValidates SESSION.md, phase tracking, context preservation
Full project health auditAll threeComprehensive 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

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

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

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

与其他工具的关系

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

Quick Start

快速开始

  1. Full audit: "Run all project-health agents on this repo"
  2. Check one aspect: "Use context-auditor to check AI-readability"
  3. Before handoff: "Use handoff-checker before I end this session"
  1. 完整审计：“在本仓库运行所有project-health Agent”
  2. 单维度检查：“使用context-auditor检查AI可读性”
  3. 交接前检查：“在我结束会话前使用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会话的效率。