我们一开始的想法，都是把项目概要、架构、API、数据表结构等等很多东西一股脑全贴进去。但实际上从实践来看，对AI来说，你应该提供一个类似index map（索引地图）的东西。

问题：什么都重要 = 什么都不重要

很多团队在给AI项目时，喜欢写一份「完美」的指引文件，把所有东西都塞进去：

• 项目背景和目标
• 整体架构图
• 所有API接口说明
• 数据库表结构
• 代码规范文档
• 团队成员分工
• ……

结果呢？指引文件300行起步，AI看晕了，每次调用都像大海捞针。

所有东西都重要，就等于都不重要。

核心原则：地图，而非手册

对AI友好的文档，第一原则是：它应该是一张「地图」而不是一本「手册」。

你要告诉AI：

• 整个项目是什么
• 需要查什么东西，去哪个索引文件看
• 当它需要时，自己去按需加载

这就跟 Skills（技能）的概念一样——渐进式加载，按需调用。

CLAUDE.md 或 AGENTS.md 保持在 100-150 行左右，不要太长。 主要内容：

• 项目定义和背景
• 关键的API、表结构或设计文档的索引路径
• 关键的Wiki路径

当AI需要具体信息时，它会自己根据索引路径去搜索对应内容。

实践方法：Wiki + Skills 联动

基于这个思路，可以建立一套「Wiki + Skills」的联动机制：

1. 生成项目Wiki
   包含：API设计思路、设计文档、架构说明

2. 基于Wiki生成指引文件
   指引文件只保留索引路径，指向对应Wiki

3. 自动化更新Wiki
   基于代码提交自动更新，避免人工维护的时效性问题

优化效果：300行 → 100行，简洁高效。

工具推荐：阿里Qoder Repo Wiki

推荐阿里的 Qoder 的 Repo Wiki 功能：

• 自动扫描整个项目源码
• 生成整体的项目Wiki
• 既能给人看，也能给AI看
• AI可以自己扫描和理解项目背景

使用场景：

1. 给人看：团队成员快速了解项目架构
2. 给AI看：AI按需加载，保持指引文件精简

总结：三个关键点

关键点	说明
精简到100-150行	指引文件不是手册，是索引
建立Wiki体系	详细内容放Wiki，指引文件只放索引
自动化更新	基于代码提交更新Wiki，保持时效性

当你把指引文件从「什么都有」变成「按需加载」，你会发现AI的响应质量和速度都会提升不少。