TypeScript for AI Agents：从摩擦到流畅与子代理

Source: Dev.to

请提供您希望翻译的完整文本（除代码块和 URL 之外），我将把它翻译成简体中文并保持原有的 Markdown 格式。

Source: …

使用 TypeScript 与 AI 代理的两难

当你让 AI 代理编写生产代码时，会面临一个根本性的两难：

• TypeScript 提供了关键的防护措施，能够防止幻觉并提前捕获错误。
• 同样的防护措施又在代理的工作流中制造了摩擦。

我最近就和 Gemini 3.0 Flash 进行过这样的对话。
问题是什么？我的 AI 代理不断陷入修复 TypeScript 编译错误的循环中，导致它们的上下文窗口被缺少导入和类型不匹配的噪音所污染，而无法专注于实际的业务逻辑。

典型的回应会是：“直接改用 Python”。
但这并不是正确的解决方案。

为什么 TypeScript 在 AI 驱动的开发中仍然更优

1. 错误在运行前就被捕获 – 当 AI 代理出现函数签名幻觉或忘记属性时，类型检查器会立刻说 “不行”。在 Python 中，这类错误可能要等到用户在生产环境点击某个特定按钮时才会显现。

2. 类型是永不过时的文档 – AI 代理阅读

   interface User {
     id: string;
     email: string;
   }

   时，能够准确知道 User 的结构。无需猜测、无需“可能有 email 字段”，也不会出现静默失败。

3. 强大的模式：让类型指导实现 – 先定义接口，TypeScript 会告诉代理到底需要实现什么。这就像高速公路上的护栏——你可以高速前进，因为知道不会掉下去。

真正的问题：单一的“思路线索”

摩擦并不是由 TypeScript 本身引起的；而是因为在 业务逻辑 与 修复编译错误 时使用了同一条思路线索。

想象你是一名建筑师，正在设计一座建筑。每当你画出一个房间时，就有人打断你：
“门框尺寸与标准目录不匹配。”
你修正后继续设计，又被打断：
“窗户位置违反了消防规范第 4.2.1 条。”

你会抓狂。这正是 AI 代理在同时进行以下工作时会出现的情况：

• 推理应用程序架构
• 实现业务逻辑
• 修复错误，例如
  • Property 'map' does not exist on type 'string'
  • Cannot find module './utils'

上下文窗口被 TypeScript 噪声填满，代理失去对原始目标的跟踪，最终导致功能只实现了一半，并且到处出现 “TODO: fix types” 的注释。

来自人类开发团队的启发

人类团队并不是由一个人完成所有工作。他们有：

每个角色都有其专门的上下文和目标。

**我将同样的模式应用到 AI 代理上：一个专门的子代理，仅处理 TypeScript 编译错误。

Source: …

我为 Claude Code 实现的架构

~/.claude/agents/typescript-fixer/AGENT.md

主代理（Architect）

• 关注点： 业务逻辑、功能实现、架构决策
• 上下文： 干净、专注于当前任务

typescript-fixer 子代理（Specialist）

• 关注点： 仅 TypeScript 编译错误
• 上下文： 错误信息 + 相关文件（仅此）
• 触发条件： 当 tsc 失败时自动调用

关键设计原则

1. 主动调用 – 主代理自动将类型错误委派给修复子代理。
2. 上下文隔离 – 修复子代理只能看到错误输出和需要修改的文件。
3. 范围狭窄 – 不进行业务逻辑更改，只做类型修复。
4. 自动解决 – 修复导入、添加类型注解、解决接口不匹配等。

修复子代理处理的内容

不 处理的内容

• 业务逻辑
• 应用架构
• 功能实现
• 命名规范（除非导致类型错误）

前后对比

之前（单一代理）

User: "Add a user authentication feature"

Agent: [writes auth logic]
Agent: [hits type error in LoginForm]
Agent: [fixes type error]
Agent: [continues feature, hits another error]
Agent: [fixes that error]
Agent: [loses context, forgets to add logout button]
User: (has to remind it)

之后（子代理架构）

User: "Add a user authentication feature"

Main Agent: [designs auth architecture]
Main Agent: [implements login/logout flow]
Main Agent: runs `tsc` → errors detected
Main Agent: "Delegating to typescript-fixer..."

typescript-fixer:
  - reads error output
  - fixes all type issues in parallel
  - reports completion

Main Agent: [continues with clean context]
Main Agent: [completes full feature including logout]

影响

子代理可以在 tsc 失败时自动调用，或在我注意到类型问题堆积时手动调用。无论哪种方式，主代理都专注于其最擅长的工作：架构和实现。

更大的教训

未来并不是在于为了“代理友好性”而在 Python 与 TypeScript 之间做选择。
关键在于 构建让代理像高效团队一样工作的工作流。

• TypeScript 的防护栏是 特性，而非 bug。它们能够捕获在 Python 中会导致生产事故的错误。
• 解决方案不是去除防护栏，而是构建 专门角色 来处理开发的不同方面。

扩展模式

相同的思路可以应用于其他关注点：

每个代理都有隔离的上下文和狭窄的范围，使主要的编码代理保持简洁且高效。

专业 AI 代理的自主开发

“文本、专业专长以及明确的任务范围。就像真实的工程团队一样。”

如果你正在使用 Claude Code，可以安装 typescript-fixer 子代理：

# Create the agent definition file
~/.claude/agents/typescript-fixer/AGENT.md

如何设置

1. 定义其范围 – 仅限类型错误，不涉及业务逻辑。
2. 设置主动触发 – 在 tsc 失败时调用。
3. 让它处理噪音，你专注于功能实现。

代码很简单，但影响深远。你可以在不牺牲自主开发流畅性的前提下，获得 TypeScript 类型系统的安全性。

想讨论 AI 代理架构吗？

• 在 LinkedIn 上联系我
• 在 javieraguilar.ai 阅读更多文章

构建未来，一次一个专用代理。 🤖

最初发表于 javieraguilar.ai。

更多 AI‑代理项目

查看我的作品集，我展示了：

• 多代理系统
• MCP 开发
• 合规自动化

查看作品集 →