54 lines
5.3 KiB
Markdown
54 lines
5.3 KiB
Markdown
|
||
以下是适用于所有仓库的通用工作约定，项目级配置可覆盖此文件的条目。
|
||
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. 白名单操作：以下操作在无需用户确认的情况下默认允许：读取文件、列出目录、格式化单个文件、运行单元测试、执行单文件类型检查或 lint 。
|
||
2. 需要确认：以下操作必须事先征求用户明确批准：安装或升级依赖、推送代码到远程仓库、删除或移动文件、运行全面构建或端到端测试 。
|
||
3. 敏感系统：对接数据库、支付系统或外部 API 时，默认使用只读模式；若需要写入或收费操作，需遵循 Supabase/Stripe 安全规程，提前展示计划和风险并等待确认。
|
||
4. 密钥与凭据：不得在代码或日志中泄露 API 密钥、数据库连接字符串或其他敏感信息。如需配置环境变量，请在本地 .env 文件中设置，并在文档中说明名称而非值。
|
||
-->
|
||
|
||
流程简化与信息流
|
||
1. 精简工具调用：将常用的多步操作整合为单个工具或脚本，减少代理和 LLM 的往返次数 。
|
||
2. 充分记录：在自定义工具中使用日志（例如打印调试信息），记录输入参数、执行步骤和错误信息，以便模型理解并调整后续动作 。
|
||
3. 明确格式：在工具文档字符串中注明输入参数的格式、单位、时间格式等；输出应该清晰易懂，并在出错时提供帮助性提示 。
|
||
|
||
测试与验证
|
||
1. 必跑测试：在所有仓库中，修改任何代码后必须运行现有测试；无测试的项目应优先创建测试框架，如 pytest、jest、vitest 等，并逐步补齐覆盖率。
|
||
2. 持续集成：鼓励在项目中配置自动化的测试、构建和静态分析，以便代理能够调用相应命令验证更改。
|
||
3. 最小化差异：提交的代码差异应局限于所需修改的文件范围；避免无关文件的自动格式化或重写 。
|
||
|
||
维护与更新
|
||
1. 作为单一真相源：将此文件视为个人或团队的 AI 代理工作手册，不应在多处复制粘贴同样的指导信息 。
|
||
2. 与代码同步：当您的工作流、构建命令或安全策略发生变化时，请同步更新此文件，并在对应的项目级别文件中适当覆盖或补充 。
|
||
<!--
|
||
3. 验证加载：如需确认 Codex 是否正确读取了本文件，可运行 codex --ask-for-approval never "Summarize the current instructions."，它将列出正在生效的指导 。
|
||
4. 临时覆盖：若需暂时覆盖全局规则，可以创建 ~/.codex/AGENTS.override.md 并在完成后删除 。
|
||
-->
|
||
|