AI 上下文文档管理

技能文档

---
name: giuseppe-trisciuoglio-claude-md-management
title: AI 上下文文档管理
description: 对项目的 AI 上下文文档（AGENTS.md、CLAUDE.md 等协作约定文件）做全面管理：全量扫描、六维质量评估打分（0-100 分与 A-F 等级）、输出质量报告并在用户确认后做针对性改进，也支持从零创建。当用户请求检查、审计、更新、改进、修复或验证项目上下文文档、优化 AI 项目记忆、评审文档质量时触发。触发词：上下文文档、AGENTS.md、CLAUDE.md、文档质量检查、项目记忆优化、审计文档。
category: 开发工具
---

# AI 上下文文档管理

提供项目 AI 上下文文档的全面管理能力：审计、质量评估与针对性改进，确保 AI 编码会话始终获得高质量的项目上下文。

## 概述

上下文文档（如项目根目录的 `AGENTS.md`、`CLAUDE.md`）是向 AI 编码会话提供项目专属上下文的主要机制。本技能管理其完整生命周期：发现 → 质量评估 → 报告 → 改进，遵循五阶段工作流，保证文档始终及时、可执行、精炼。

评估基于 6 个维度的标准化质量准则：命令与工作流、架构清晰度、非显而易见的模式、精炼度、时效性、可执行性。每个文件获得 0-100 分与 A-F 等级，并附具体改进建议。

## 何时使用

- 用户明确要求「检查 / 审计 / 更新 / 改进 / 修复 / 维护」上下文文档
- 用户提到「文档质量」「项目记忆优化」「AI 上下文评审」
- 新项目需要从零创建上下文文档
- 用户希望改进 AI 对代码库的理解
- 文档已陈旧过时
- 接手新代码库，需要理解既有文档

**触发语示例**：「审计一下 AGENTS.md」「检查文档质量」「改进项目上下文」「评审 CLAUDE.md」「验证文档有效性」

## 技能工作流

### 步骤1：发现

找出仓库中所有上下文文档：

```bash
find . -name "AGENTS.md" -o -name "CLAUDE.md" -o -name ".claude.local.md" 2>/dev/null | head -50
```

**文件类型与位置：**

| 类型 | 位置 | 用途 |
|------|------|------|
| 项目根目录 | `./AGENTS.md` 或 `./CLAUDE.md` | 项目主上下文（入库 git，团队共享） |
| 本地覆盖 | `./.claude.local.md` 等 | 个人本地配置（gitignore，不共享） |
| 全局默认 | `~/.claude/CLAUDE.md` 等 | 跨项目的用户级默认 |
| 包级 | `./packages/*/AGENTS.md` | monorepo 的模块级上下文 |
| 子目录 | 任意嵌套位置 | 特性/领域专属上下文 |

### 步骤2：质量评估

对每个文件，阅读 [references/quality-criteria.md](references/quality-criteria.md) 并按以下准则评估：

| 准则 | 分值 | 检查内容 |
|------|------|---------|
| 命令与工作流 | 20 分 | 构建/测试/部署命令是否齐全且可用 |
| 架构清晰度 | 20 分 | AI 能否借此理解代码库结构 |
| 非显而易见的模式 | 15 分 | 坑点与怪癖是否已记录 |
| 精炼度 | 15 分 | 内容是否紧凑无注水 |
| 时效性 | 15 分 | 是否反映代码库当前状态 |
| 可执行性 | 15 分 | 指令是否可直接复制执行 |

**等级：** A（90-100）、B（70-89）、C（50-69）、D（30-49）、F（0-29）

### 步骤3：输出质量报告

**关键要求：任何更新之前，必须先输出质量报告。**

格式：

```markdown
## 上下文文档质量报告

### 概要
- 发现文件数：X
- 平均分：X/100
- 需要更新的文件数：X

### 逐文件评估
#### 1. ./AGENTS.md（项目根目录）
**得分：XX/100（等级：X）**

| 准则 | 得分 | 说明 |
|------|------|------|
| 命令与工作流 | X/20 | ... |
| 架构清晰度 | X/20 | ... |
| 非显而易见的模式 | X/15 | ... |
| 精炼度 | X/15 | ... |
| 时效性 | X/15 | ... |
| 可执行性 | X/15 | ... |

**问题：**
- [列出具体问题]

**建议补充：**
- [列出应当补充的内容]
```

### 步骤4：提出针对性更新

输出报告后，先征得用户确认再更新。

**更新原则详见 [references/update-guidelines.md](references/update-guidelines.md)。**

核心原则：
1. **只提出针对性补充** —— 命令、坑点、模式、配置
2. **保持最小** —— 不写显而易见的信息、泛泛建议、一次性修复
3. **展示 diff** —— 文件、变更（diff 格式）、理由

Diff 格式示例：

````markdown
### 更新：./AGENTS.md
**理由：** [简述为什么这样有帮助]

```diff
+ ## 快速开始
+
+ ```bash
+ npm install
+ npm run dev
+ ```
```
````

### 步骤5：应用更新

用户确认后应用变更，保留既有内容结构。

## 示例

### 示例1：质量评估

**用户请求**：「检查我的 AGENTS.md 写得好不好」

**响应要点**：

```markdown
## 上下文文档质量报告

### 概要
- 发现文件数：1
- 平均分：65/100
- 需要更新的文件数：1

#### 1. ./AGENTS.md
**得分：65/100（等级：C）**

| 准则 | 得分 | 说明 |
|------|------|------|
| 命令与工作流 | 10/20 | 只记录了 npm install |
| 架构清晰度 | 15/20 | 有基础目录树，缺模块关系 |
| 非显而易见的模式 | 5/15 | 没有记录坑点 |
| 精炼度 | 15/15 | 紧凑无注水 |
| 时效性 | 10/15 | 部分路径已过时 |
| 可执行性 | 10/15 | 部分指令含糊 |

**问题：**
- 缺测试命令与构建命令
- 未记录认证模块的复杂坑点
- 引用了旧的 src/ 结构
```

### 示例2：从零创建

**用户请求**：「为这个 React 项目创建一份 AGENTS.md」

**响应要点**：先扫描 `package.json`、`src/` 与关键配置文件，然后按「命令 / 架构 / 坑点」三段结构生成提案，经用户确认后落盘。

### 示例3：更新提案

**用户请求**：「把这次学到的更新进文档」

**响应要点**：

```diff
## 测试

+ **前置条件：** 先用 `docker-compose up -d test-db` 启动测试数据库
+ `npm run test` —— 运行全部测试
+ `npm run test:unit` —— 仅单元测试（无需数据库）
```

```diff
## 环境变量

- `API_BASE_URL` —— API 地址（默认 localhost:3000）
+ `API_BASE_URL` —— API 地址（生产必填，开发环境默认 http://localhost:3000）
```

应用这些变更吗？

## 最佳实践

1. **动手前先读参考文件**：质量准则、模板与更新指南含关键细节
2. **先报告后编辑**：未经质量报告展示，绝不修改文档
3. **保留既有结构**：更新时维持文件原有组织与风格
4. **只写项目专属内容**：不加通用建议，只写本代码库特有信息
5. **验证命令可用**：提出命令前先（在心里或实际）验证其可执行
6. **渐进式披露**：正文保持精炼，评分细则放独立参考文件
7. **一致评分**：对所有文件使用同一评分标准，保证可比性

## 约束与警告

1. **未经确认不修改**：编辑前必须获得用户确认
2. **不擅自删内容**：建议删除时明确标注并征求同意
3. **尊重个人本地配置**：`.claude.local.md` 等本地文件是个人设置，不建议写入共享文档
4. **避免泛泛建议**：不写「好好写代码」式内容，聚焦项目专属模式
5. **diff 保持精简**：只展示实际变更，不贴整个文件
6. **核实文件路径**：文档化前确认引用的文件真实存在
7. **客观评分**：坚持统一标准，不给不完整的文档虚高分

使用说明

# AI 上下文文档管理

对项目的 AI 上下文文档（AGENTS.md、CLAUDE.md 等协作约定文件）做扫描、六维质量评估打分、输出报告，并经确认后针对性改进，支持从零创建。

## 适用场景

- 检查 / 审计 / 更新 / 改进项目的 AGENTS.md 或 CLAUDE.md
- 新项目从零创建上下文文档
- 文档陈旧、AI 理解代码库效果差
- 接手新代码库时评估文档质量

## 使用方式

对 AI 助手说：

```text
审计一下我的 AGENTS.md 质量
检查文档质量，给出评分和改进建议
为这个 React 项目创建一份上下文文档
```

## 评估维度

命令与工作流（20 分）、架构清晰度（20 分）、非显而易见的模式（15 分）、精炼度（15 分）、时效性（15 分）、可执行性（15 分），总分 0-100，等级 A-F。

## 输出内容

- 逐文件质量报告：得分、等级、问题清单、建议补充项
- 确认后以 diff 形式给出针对性更新提案

## 注意事项

- 任何更新前必先输出质量报告并征得确认
- 个人本地配置文件（如 .claude.local.md）不会被建议改动

如何安装此技能？

访问技能市场，点击「安装」按钮，按提示将技能包放入 AI 编程助手的 skills 目录即可。