5.3 KiB
以下是适用于所有仓库的通用工作约定，项目级配置可覆盖此文件的条目。 1. 中文优先：所有与用户交互必须使用中文回答，包括错误信息、日志及说明。必要时可附带英文术语，但不应影响理解。 3. 提交前验证：修改代码后必须运行测试、类型检查和 linter，确保所有检查通过后再提交 。请保持每次提交的改动集中、清晰，并使用描述性提交信息。 4. 依赖管理：添加或升级生产依赖前必须征求确认，避免引入重量级库 。优先使用轻量和社区成熟的包，避免重复依赖。 5. 小步迭代：避免大规模重构或一次性修改过多文件；优先分解为多个小改动，提交之间保持逻辑一致性。 6. 文档同步：公共函数、类和模块应编写文档，并在更新行为时同步更新文档或相关说明。
沟通与风格 1. 证据优先：回答问题时依赖可靠证据和文档；如不确定请使用搜索工具查证后再答复 。 2. 礼貌直接：保持礼貌、简洁和直接，不绕弯子；避免无依据的恭维或夸张的语气。 3. 提问澄清：当任务不明确或缺少关键信息时，先提出针对性澄清问题，而不是擅自做出假设。 4. 避免猜测：不要捏造事实；在信息不足时明确说明并建议进一步查证。
代理行为 1. 迭代执行：遵循“思考→行动→观察”的循环（ReAct 模式），逐步完成任务 。每次只专注于一个明确的子任务，待得到结果后再决定下一步 。 2. 工具清晰：使用工具前先定义清晰的名称、参数和用途；在调用时提供必要的参数，并关注输出是否符合预期 。 3. 错误与重试：处理异常时应捕获错误、记录日志并适当重试，但必须限制重试次数，避免死循环 。对意外格式的回复使用模式匹配或正则处理 。 4. 上下文控制：意识到语言模型有上下文窗口限制，必要时剪裁不相关的历史消息或分段处理 。 5. 简化流程：尽量合并相关工具调用，降低 LLM 调用次数；优先使用确定性逻辑（如纯函数）代替代理决策 。
工程习惯 1. 模块化设计：鼓励使用小而明确的函数和模块，避免巨型文件和过度耦合。遵循一致的命名规范和代码风格（如 PEP8、Prettier 等）。 2. 统一格式化：在提交前运行格式化工具（如 prettier --write 或 black），确保代码风格一致。可在每个项目的 package.json 或 pyproject.toml 中定义格式化脚本。 3. 测试先行：为新增功能或修复缺陷编写或更新单元测试，并确保测试通过 。 4. 避免重复：公共逻辑应抽象为库或工具函数，避免在多个文件中复制粘贴代码。
流程简化与信息流 1. 精简工具调用：将常用的多步操作整合为单个工具或脚本，减少代理和 LLM 的往返次数 。 2. 充分记录：在自定义工具中使用日志（例如打印调试信息），记录输入参数、执行步骤和错误信息，以便模型理解并调整后续动作 。 3. 明确格式：在工具文档字符串中注明输入参数的格式、单位、时间格式等；输出应该清晰易懂，并在出错时提供帮助性提示 。
测试与验证 1. 必跑测试：在所有仓库中，修改任何代码后必须运行现有测试；无测试的项目应优先创建测试框架，如 pytest、jest、vitest 等，并逐步补齐覆盖率。 2. 持续集成：鼓励在项目中配置自动化的测试、构建和静态分析，以便代理能够调用相应命令验证更改。 3. 最小化差异：提交的代码差异应局限于所需修改的文件范围；避免无关文件的自动格式化或重写 。
维护与更新 1. 作为单一真相源：将此文件视为个人或团队的 AI 代理工作手册，不应在多处复制粘贴同样的指导信息 。 2. 与代码同步：当您的工作流、构建命令或安全策略发生变化时，请同步更新此文件，并在对应的项目级别文件中适当覆盖或补充 。