Imported from liliwen88/AgentForge (AGENTS.md). Install upstream with npx skills add liliwen88/AgentForge. Copyright stays with the author.

AgentForge AI编程助手指导原则

本项目定位为面向业务开发的 TypeScript 全栈 + AI 脚手架，目标是让企业业务功能开发对标主流 AI 编程助手，像搭积木一样快速构建产品，而不是专注于 AI Agent 平台本身。

基于Andrej Karpathy观察到的LLM编程行为优化，专为AgentForge项目设计的AI编程助手指导原则。

核心原则

1. 思考先于编码

不要假设。不要隐藏困惑。暴露权衡。

在实现之前：

• 明确陈述假设 - 如果不确定，询问而不是猜测
• 呈现多种解释 - 当存在歧义时不要默默选择
• 在必要时提出反对 - 如果存在更简单的方法，说明原因
• 困惑时停止 - 明确指出不清楚的地方并寻求澄清

2. 简洁优先

最小代码解决实际问题。不做推测。

对抗过度工程化倾向：

• 不添加超出要求的功能
• 不为单用途代码创建抽象
• 不添加未要求的"灵活性"或"可配置性"
• 不为不可能的场景添加错误处理
• 如果200行代码可以写成50行，重写它

测试标准： 高级工程师会说这是过度复杂吗？如果是，简化它。

3. 精确修改

只触碰必须的部分。只清理自己的烂摊子。

编辑现有代码时：

• 不要"改进"相邻代码、注释或格式
• 不要重构未损坏的内容
• 匹配现有风格，即使你会用不同方式
• 如果注意到无关的死代码，提及它 - 不要删除它

当你的更改产生孤立代码时：

• 删除你的更改导致未使用的导入/变量/函数
• 不要删除预存在的死代码，除非被要求

测试标准： 每个更改的行都应该直接追溯到用户的请求。

4. 目标驱动

定义成功标准。循环直到验证。

将命令式任务转化为可验证目标：

对于多步骤任务，陈述简要计划：

1. [步骤] → 验证: [检查]
2. [步骤] → 验证: [检查]
3. [步骤] → 验证: [检查]

强成功标准让AI独立循环。弱标准（"让它工作"）需要持续澄清。

AgentForge特定规则

业务开发优先

• 本项目优先支持业务功能开发，而不是构建 AI Agent 产品。
• 设计应以 TypeScript 全栈脚手架为核心，最大化与主流 AI 编程助手的协作效率。
• 目标是替代传统 SaaS 和低代码方案，提供可扩展、可维护的企业级业务开发基础。
• 代码结构应便于 AI 编程助手理解，因此应保持简单、直观、模块化。

Agent开发约束

禁止过度抽象：

• 不要为单一Agent创建基类
• 不要为简单消息处理创建复杂状态机
• 避免为3个以下的Agent创建注册表系统

优先使用内置功能：

• 使用BaseAgent而不是重新实现
• 使用内置工具而不是重复造轮子
• 使用内置记忆系统而不是自定义实现

Agent配置原则：

• 配置应该简单且可读
• 避免嵌套配置对象
• 为常用场景提供默认值

业务逻辑指导

专注业务价值：

• 每个Agent都应该解决具体的业务问题
• 避免为技术而技术的功能
• 优先考虑用户体验而不是技术炫技

错误处理边界：

• 只处理可能发生的错误
• 不要为不可能的场景添加防御性编程
• 错误消息应该对用户有意义

性能考虑：

• 不要过早优化
• 只在确实存在性能问题时才优化
• 优先考虑代码可读性而不是微优化

集成测试要求

Agent测试：

• 每个Agent都需要集成测试
• 测试应该覆盖主要用户场景
• 使用模拟数据而不是真实API调用

工具测试：

• 每个自定义工具都需要单元测试
• 测试边界情况和错误条件
• 验证输入schema的正确性

端到端测试：

• 关键工作流需要端到端测试
• 测试应该模拟真实用户行为
• 使用测试环境而不是生产环境

性能边界提示

内存使用：

• Agent记忆应该有合理的大小限制
• 避免无限增长的数据结构
• 定期清理不需要的数据

并发处理：

• 不要创建无限循环的Agent
• 使用适当的超时机制
• 避免阻塞主线程

API调用：

• 实现适当的速率限制
• 缓存频繁请求的结果
• 优雅处理API错误和重试

项目特定指导

代码风格

• 使用TypeScript严格模式
• 所有导出函数和类都需要JSDoc注释
• 优先使用函数式编程而不是面向对象
• 使用ESLint和Prettier进行格式化

文件组织

src/
├── agents/          # Agent定义文件
├── tools/           # 自定义工具
├── components/      # UI组件
└── utils/           # 工具函数

命名约定

• Agent文件使用kebab-case：chat-agent.ts
• 类名使用PascalCase：ChatAgent
• 函数名使用camelCase：sendMessage
• 常量使用UPPER_SNAKE_CASE：MAX_MEMORY_SIZE

导入导出

• 优先使用命名导出而不是默认导出
• 按照类型分组导入：第三方库 → 内部模块 → 相对路径
• 避免深度嵌套的导入路径

反模式示例

❌ 过度抽象

// 不要这样做
abstract class AgentBase {
  abstract processMessage(message: Message): Promise<void>;
  abstract handleError(error: Error): void;
}

class ChatAgent extends AgentBase {
  // 大量样板代码
}

✅ 简单直接

// 应该这样做
export class ChatAgent extends BaseAgent {
  protected async handleMessage(message: Message): Promise<void> {
    // 直接实现逻辑
  }
}

❌ 过度配置

// 不要这样做
interface AgentConfig {
  name: string;
  behavior: {
    responseStyle: 'formal' | 'casual' | 'technical';
    personality: {
      friendliness: number; // 0-100
      humor: number; // 0-100
      professionalism: number; // 0-100
    };
  };
}

✅ 简单配置

// 应该这样做
interface AgentConfig {
  name: string;
  description: string;
  model: string;
  temperature: number;
  tools: string[];
}

验证检查清单

在提交代码前，问自己：

1. 思考先于编码

   • 我明确陈述了我的假设吗？
   • 我暴露了重要的权衡吗？
   • 我在不确定时寻求澄清了吗？

2. 简洁优先

   • 代码是否尽可能简单？
   • 我添加了未要求的功能吗？
   • 我创建了不必要的抽象吗？

3. 精确修改

   • 我只修改了必要的部分吗？
   • 我匹配了现有代码风格吗？
   • 我清理了自己的烂摊子吗？

4. 目标驱动

   • 我定义了成功标准吗？
   • 我的代码可以被验证吗？
   • 我将任务转化为可验证目标了吗？

这些指导原则有效的标志

如果你看到以下情况，说明指导原则正在工作：

• 更少的必要更改在diff中 - 只出现请求的更改
• 更少的重写由于过度复杂 - 代码第一次就是简单的
• 澄清问题在实现之前出现 - 而不是在错误之后
• 干净、最小化的PR - 没有顺便的重构或"改进"

权衡说明

这些指导原则偏向谨慎而非速度。对于琐碎任务（简单拼写修正、明显的一行代码），使用判断力 - 不是每个更改都需要完全的严谨。

目标是在非平凡工作上减少代价高昂的错误，而不是减慢简单任务。

记住：好的代码是简单解决今天问题的代码，而不是过早解决明天问题的代码。