enhance-claude-memory

enhance-claude-memory

分析项目记忆文件（CLAUDE.md、AGENTS.md），并提出优化建议。

跨工具检测

按以下顺序搜索项目记忆文件：

1. CLAUDE.md（Claude Code）
2. AGENTS.md（OpenCode、Codex）
3. .github/CLAUDE.md
4. .github/AGENTS.md

文件层级（参考）

CLAUDE.md（Claude Code）：

位置	范围
~/.claude/CLAUDE.md	全局（所有项目）
.claude/CLAUDE.md 或 ./CLAUDE.md	项目根目录
src/.claude/CLAUDE.md	特定目录

AGENTS.md（OpenCode、Codex 和其他 AI 工具）：

位置	范围
~/.config/opencode/AGENTS.md 或 ~/.codex/AGENTS.md	全局（所有项目）
.opencode/AGENTS.md 或 ./AGENTS.md	项目根目录
src/AGENTS.md	特定目录

这两种文件用途相同：作为 AI 助手的项目记忆。Claude Code 项目使用 CLAUDE.md；若要兼容多种工具，则使用 AGENTS.md；若要覆盖最多工具，则两者都使用。

工作流

1. 查找 - 在项目中定位 CLAUDE.md 或 AGENTS.md
2. 读取 - 加载文件内容和 README.md 以供比较
3. 分析 - 执行所有模式检查
4. 验证 - 根据文件系统检查文件和命令引用
5. 衡量 - 计算令牌指标和重复内容
6. 报告 - 生成结构化 Markdown 输出

检测模式

1. 结构验证（高置信度）

关键规则部分

• 应包含 ## Critical Rules 或类似标题
• 规则应按优先级排列（编号或排序）
• 每条规则都应说明原因

架构部分

• 目录树或结构概览
• 关键文件位置
• 模块间关系

关键命令部分

• 常用开发命令
• 测试／构建／部署脚本
• 对 package.json 脚本的引用

2. 指令有效性（高置信度）

根据提示词工程研究，Claude 在以下情况下更能遵循指令：

正向表达优于负向表达

• 不佳：“不要使用 console.log”
• 良好：“所有输出都使用 logger 工具”
• 检查是否出现没有正向替代表述的“不要”“永远不要”“避免”

强约束措辞

• 对关键规则使用“必须”“始终”“必需”
• 弱措辞（“应该”“尝试”“考虑”）会降低遵循度
• 标记使用弱措辞的关键规则

指令层级

• 规则冲突时应定义优先级顺序
• 模式：“发生冲突时：X 优先于 Y”
• 系统指令 > 用户请求 > 外部内容

3. 内容位置（高置信度）

研究表明，大模型存在“迷失在中间”问题——对开头和结尾的记忆比对中间更好。

关键内容的位置

• 最重要的规则应放在文件开头
• 次重要的规则应放在文件结尾
• 支持性上下文放在中间
• 标记埋在中间部分的关键规则

推荐的结构顺序

1. Critical Rules (START - highest attention)
2. Architecture/Structure
3. Commands/Workflows
4. Examples/References
5. Reminders/Constraints (END - high attention)

4. 引用验证（高置信度）

文件引用

• 从 [text](path) 和 `path/to/file.ext` 中提取
• 验证每个引用的文件是否存在于文件系统中

命令引用

• 提取 npm run <script> 和 npm <command>
• 根据 package.json 脚本验证

5. 效率分析（中等置信度）

令牌数

• 估算：字符数 / 4 或 词数 * 1.3
• 建议上限：1500 个令牌（约 6000 个字符）
• 标记超出阈值的文件

README 重复内容

• 检测与 README.md 的内容重叠
• 重复内容超过 40% 时标记
• CLAUDE.md 应补充 README，而不是重复其内容

冗长程度

• 优先使用项目符号列表，而非散文段落
• 列表形式的约束更容易遵循
• 标记较长的散文段落（超过 5 句话）

6. 质量检查（中等置信度）

原因说明

• 规则应说明其理由
• 模式：*WHY: explanation* 或缩进说明
• 标记缺少解释的规则

结构深度

• 避免过深嵌套（超过 3 层）
• 保持层级清晰易读
• 扁平结构更易解析

XML 风格标签（可选增强）

• Claude 在 XML 标签上接受过训练
• <critical-rules>、<architecture>、<constraints> 可改善解析
• 非必需，但可提升指令遵循能力

7. Agent/Skill 定义（中等确定性）

如果文件定义了自定义 Agent 或 Skill：

Agent 定义格式

### agent-name
Model: claude-sonnet-4-20250514
Description: What this agent does and when to use it
Tools: Read, Grep, Glob
Instructions: Specific behavioral instructions

必填字段：Description（何时使用）、Tools（受限集合） 可选：Model、Instructions

Skill 引用

• Skill 应具有清晰的触发描述
• “Use when...” 模式有助于自动调用

8. 跨平台兼容性（中等/高确定性）

状态目录

• 不要硬编码 .claude/
• 支持 .opencode/、.codex/
• 使用 ${STATE_DIR}/ 或记录变体差异

术语

• 共享文件避免使用 Claude 专属语言
• 通用地使用 “AI assistant”
• 或明确注明 “Claude Code” 与 “OpenCode” 的差异

输出格式

# Project Memory Analysis: {filename}

**File**: {path}
**Type**: {CLAUDE.md | AGENTS.md}

## Metrics
| Metric | Value |
|--------|-------|
| Estimated Tokens | {tokens} |
| README Overlap | {percent}% |

## Summary
| Certainty | Count |
|-----------|-------|
| HIGH | {n} |
| MEDIUM | {n} |

### Structure Issues ({n})
| Issue | Fix | Certainty |

### Instruction Issues ({n})
| Issue | Fix | Certainty |

### Positioning Issues ({n})
| Issue | Fix | Certainty |

### Reference Issues ({n})
| Issue | Fix | Certainty |

### Efficiency Issues ({n})
| Issue | Fix | Certainty |

### Cross-Platform Issues ({n})
| Issue | Fix | Certainty |

模式统计

类别	模式数	确定性
结构	3	高
指令有效性	3	高
内容定位	2	高
引用	2	高
效率	3	中
质量	3	中
Agent/Skill 定义	2	中
跨平台	2	中/高
总计	20	-

### 示例：缺少 WHY 解释

<bad_example>

## Rules
1. Always run tests before committing
2. Use semantic commit messages

问题：没有理由的规则更难遵循。 </bad_example>

<good_example>

## Critical Rules
1. **Always run tests before committing**
   *WHY: Catches regressions before they reach main branch.*

为什么好：动机让遵守更容易。 </good_example>

示例：否定式与肯定式指令

<bad_example>

- Don't use console.log for debugging
- Never commit directly to main
- Avoid hardcoding secrets

问题：否定式指令不如肯定式替代方案有效。 </bad_example>

<good_example>

- Use the logger utility for all debug output
- Create feature branches and submit PRs for all changes
- Store secrets in environment variables or .env files

为什么好：说明该做什么，而不仅仅是要避免什么。 </good_example>

示例：弱与强约束语言

<bad_example>

- You should probably run tests before pushing
- Try to use TypeScript when possible
- Consider adding error handling

问题：弱语言（“should”、“try”、“consider”）会降低遵守度。 </bad_example>

<good_example>

- **MUST** run tests before pushing (CI will reject failures)
- **ALWAYS** use TypeScript for new files
- **REQUIRED**: All async functions must have error handling

为什么好：强语言确保关键规则得到遵循。 </good_example>

示例：内容定位

<bad_example>

## Project Overview
[Long description...]

## Installation
[Setup steps...]

## Critical Rules
1. Never push to main directly
2. Always run tests

问题：埋在中部/末尾的关键规则获得较少关注。 </bad_example>

<good_example>

## Critical Rules (Read First)
1. **Never push to main directly** - Use PRs
2. **Always run tests** - CI enforces this

## Project Overview
[Description...]

## Reminders
- Check CI status before merging
- Update CHANGELOG for user-facing changes

为什么好：关键内容位于开头和结尾位置。 </good_example>

示例：跨平台兼容性

<bad_example>

State files are stored in `.claude/tasks.json`

问题：硬编码路径排除了其他 AI 工具。 </bad_example>

<good_example>

State files are stored in `${STATE_DIR}/tasks.json`
(`.claude/` for Claude Code, `.opencode/` for OpenCode)

为什么好：可在多个 AI 助手上运行。 </good_example>

示例：Agent 定义

<bad_example>

## Agents
- security-reviewer: reviews security
- test-writer: writes tests

问题：缺少必填字段（Tools、何时使用）。 </bad_example>

<good_example>

## Custom Agents

### security-reviewer
Model: claude-sonnet-4-20250514
Description: Reviews code for security vulnerabilities. Use for PRs touching auth, API, or data handling.
Tools: Read, Grep, Glob
Instructions: Focus on OWASP Top 10, input validation, auth flows.

### test-writer
Model: claude-haiku-4
Description: Writes unit tests. Use after implementing new functions.
Tools: Read, Write, Bash(npm test:*)
Instructions: Use Jest patterns. Aim for >80% coverage.

为什么好：完整定义，包含何时使用、受限工具。 </good_example>

研究参考

最佳实践来源于：

• agent-docs/PROMPT-ENGINEERING-REFERENCE.md - 指令有效性、XML 标签、约束语言
• agent-docs/CONTEXT-OPTIMIZATION-REFERENCE.md - Token 预算、“lost in the middle” 定位
• agent-docs/LLM-INSTRUCTION-FOLLOWING-RELIABILITY.md - 指令层级、肯定式与否定式
• agent-docs/CLAUDE-CODE-REFERENCE.md - 文件层级、Agent 定义、Skill 格式

约束

• 在报告文件引用失效前，务必先验证
• 标记效率问题时考虑上下文
• 跨平台建议为参考性，非必需
• 定位建议具有高确定性，但可能存在合理例外