ai-steering-files

AI 指导文件

概述

AI 指导文件是仓库本地的上下文文档，用于指导编码 Agent 如何在项目中工作。添加能够消除反复出现的歧义的最小文件，并确保内容足够具体，让 Agent 无需猜测就能采取行动。

适用场景

在以下情况下使用此技能：

• 添加或修订面向 AI 编码 Agent 的仓库说明
• 在 AGENTS.md、工具专属说明文件以及产品或技术上下文文件之间做选择
• 检查仓库是否为 Agent 提供了足够的命令、约束和示例
• 引入需要专属记忆、语法或范围规则的新 Agent 工具

不要将其用于一次性聊天指令、临时实现备注，或与仓库内容无关的通用建议。

工作流

1. 创建新文件前，先盘点现有的指导文件。阅读已有的 AGENTS.md、CLAUDE.md、GEMINI.md、.github/copilot-instructions.md、.cursor/rules/*.mdc、PRODUCT.md、ANALYTICS.md、TECH.md、STRUCTURE.md、VISION.md 和 DESIGN.md。
2. 为说明选择最适合长期保留且范围最窄的位置。适用于整个仓库、与供应商无关的规则应放在 AGENTS.md 中；工具专属规则应放在该工具的文件中；限定路径的规则应放在路径专属规则文件中。
3. 编写具体的仓库事实：准确的命令、准确的路径、可靠的示例、已知约束和审查要求。
4. 尽量使用链接和简短摘要，避免重复冗长的第三方文档。
5. 编辑时移除过时或重复的指导。相互冲突的文件会让 Agent 随机选择。
6. 验证提及的命令或路径。如果无法在本地运行某条命令，应在文件中说明原因。

文件选择指南

文件	适用场景	应包含的内容
AGENTS.md	规则应适用于仓库中的任何编码 Agent。	项目摘要、工作流、准确的安装／测试／构建命令、分支策略、审查要求、需经批准的高风险操作。
PRODUCT.md	实现决策需要产品上下文。	用户、问题、核心工作流、业务目标、成功标准、范围内与范围外的边界。
ANALYTICS.md	Agent 需要关于如何衡量产品行为的长期契约。	权威指标和漏斗、事件与属性架构、身份与归因规则、隐私边界、验证和架构演进。
TECH.md	Agent 需要了解技术栈和集成约束。	框架、运行时、首选库、外部服务、部署目标、支持的命令。
STRUCTURE.md	Agent 总是把文件放错位置。	目录结构图、所有权边界、导入规则、命名约定、文件放置规则。
VISION.md	长期方向应超越单个规格说明而持续保留。	长期有效的产品愿景、非目标、审美方向、不应偏离的内容、结果层面的成功标准。
DESIGN.md	Agent 生成 UI，需要设计系统指南。	设计令牌、字体排印、间距、布局约束、组件模式、无障碍规则、视觉反模式。
CLAUDE.md	Claude Code 需要持久的工具专属指导。	Claude 专属工作流说明、构建／测试要求、升级处理边界、Claude 应特殊对待的路径。
GEMINI.md	Gemini CLI 需要持久的工具专属指导。	Gemini 专属项目上下文、约定、命令和文件优先级。
.github/copilot-instructions.md	GitHub Copilot 需要仓库级说明。	构建／测试命令、编码标准、约束、审查指南、指向权威示例的链接。
.cursor/rules/*.mdc	Cursor 规则仅应适用于特定文件或工作流。	适用范围、glob 模式、该范围内的约定、示例、自动应用或手动应用行为。

质量标准

优秀的指导文件应当：

• 说明文件的用途，以及适用的读者
• 包含 Agent 可以运行的命令，而不是含糊的偏好
• 指向仓库中已有的示例
• 明确列出与安全、数据、性能、无障碍、产品和部署相关的重要约束
• 简短到足以在实际工作中反复阅读

常见错误

错误	修正方法
在每个文件中添加所有偏好。	将共享规则放在 AGENTS.md 中，再让特定工具的文件只补充差异。
编写泛泛的 Agent 建议。	用项目特定的路径、命令和示例替换。
复制冗长的外部文档。	总结其对本地项目的影响，并链接到主要来源。
为临时工作创建新文件。	将临时笔记保留在任务、问题或计划中；指导文件应当长期有效。
任由文件之间存在冲突。	指定一个权威文件，并让其他文件引用它。

最终检查

完成前，请确认：

• 所选文件与指导内容的适用范围相符
• 文件名和路径准确无误，包括大小写
• 安装、测试、lint、构建和部署命令均为最新
• 示例和链接均有效
• 结果说明了何时值得添加该文件，而不只是说明它是什么