safe_wallet AGENTS.md

AGENTS.md

本文件面向在仓库中工作的所有 AI agent。目标是提供一套通用、稳定、可执行的协作规范，减少误改、返工和低质量提交。

如无更高优先级的人类指令，默认遵守本文件。若与用户直接要求冲突，以用户要求为准。

1. 沟通原则

• 回复应直接、具体、可执行，避免空泛总结。
• 先理解需求，再行动；不要凭印象修改代码或文档。
• 如果存在不确定性，优先通过阅读代码、测试、配置和历史改动获取上下文。
• 不要把未经验证的推测表述成事实。

2. 工作方式

• 优先做小而准的改动，避免顺手大改、顺手重构、顺手重命名。
• 先找根因，再修问题；不要用堆补丁的方式掩盖症状。
• 涉及行为变更或 bug 修复时，优先先补失败测试，再写实现。
• 如果用户已经手动改过代码，不要覆盖、回退或重排这些改动。
• 如果 AI 生成代码后用户又手动修改了相关代码，后续一律以用户手动修改后的版本为准，不要恢复、覆盖或重写回 AI 之前生成的版本。
• 如果用户手动修改了代码，除非能证明该修改存在 bug，否则对应单元测试应按用户修改后的代码行为同步调整；不要为了让旧测试通过而反向修改或覆盖用户代码。
• 工作区可能是脏的；除非用户明确要求，否则不要清理与当前任务无关的改动。

3. 代码修改边界

• 架构实现、模块划分、依赖方向和目录组织必须遵循根目录的 ARCHITECTURE.md；如任务确需调整架构，应先说明原因，并同步更新该文档。
• UI、交互、视觉样式、设计 Token 和组件使用必须遵循根目录的 DESIGN.md；优先复用已有设计体系，不得自行引入与规范冲突的样式。
• 不得擅自引入新依赖、升级依赖或替换基础设施，除非用户明确要求。
• 不要随意改变现有模块的架构风格；优先遵循当前文件和当前模块已有模式。
• 改动前优先复用现有组件、工具函数、helper、resolver、测试基建和样式体系。
• 修改应尽量落在根因层，不要只在 UI 或调用层“遮住问题”。
• 不要因为“顺手”去修改与当前任务无关的文件。

4. Git 规则

• 未收到用户明确指令时，禁止执行 git commit、git push、gh pr create。
• 禁止使用破坏性命令，例如：
  • git reset --hard
  • git checkout -- <file>
  • 强制回滚或覆盖用户改动
• 需要提交时，只提交与当前任务相关的文件。
• 提交前先看 git status，确认本次提交范围准确。

5. Subagent 规则

• 用户不主动要求时，不要使用 subagent。
• 不要把“想更快一点”“想并行一点”“想多看几个方向”当成使用 subagent 的理由。
• 只有当用户明确要求使用 subagent、委派、并行 agent、子代理协作时，才可以使用。

6. 验证要求

• 不要在没有验证证据的前提下宣称“修好了”“已完成”“可以提交”。
• 优先运行与改动最相关的定向测试；必要时再扩大验证范围。
• 如果没有合适的现成测试，至少补最小回归测试，或明确说明为什么无法补。
• 如果测试或验证没有跑通，必须明确说明：
  • 没跑成什么
  • 为什么没跑成
  • 当前剩余风险是什么

7. 调试要求

• 先复现或先定位可证明的根因，再修改实现。
• 多层问题要先梳理数据流：
  • 输入从哪里来
  • 参数如何传递
  • 数据如何转换
  • 最终在哪里展示或生效
• 连续两三次修补都没解决时，停下来重新审视设计，不要继续堆补丁。

8. 文档与规范维护

• 如果仓库存在通用协作规范文件，优先维护在根目录，例如 AGENTS.md。
• 如果新增了后续 agent 也需要遵守的重要规则，应同步更新本文件。
• 本文件应保持通用，不绑定具体业务、具体框架、具体目录结构，除非用户明确要求写成项目定制版。