AI编程助手越帮越乱？TypeScript类型约束与Markdown提示词工程解法

1. 从“越帮越乱”说起：AI 编程助手到底卡在哪

用 AI 编程助手写代码这件事，这两年几乎成了开发者的标配。补全、生成、重构、写测试，工具换了一茬又一茬，但很多人心里都有一个共同的疙瘩：它有时候确实快，但越到后面越乱。小项目里感觉像神，大项目里感觉像“猪队友”——改一个函数，它顺手把你三个文件搞崩；让它加个类型，它给你整出一堆any；你让它按项目规范来，它偏要自创一套风格。

这个“越帮越乱”的现象，不是模型不够聪明，而是上下文没喂对、约束没给够、协作方式没设计好。标题里提到“93K Star 的解法，来自 TypeScript 圈最硬的那个人”，指向的其实是 TypeScript 生态里一个被反复验证过的思路：用类型系统 + 明确的工程约束，把 AI 的自由度收进一个可控的笼子里。TypeScript 本身就是一门“用类型约束行为”的语言，而它在 AI 编程助手场景下的价值，远不止“写起来更安全”这么简单。

这篇文章我想聊的不是某个具体工具怎么装、怎么点按钮，而是一套可复用的方法论：怎么让 AI 编程助手从“越帮越乱”变成“越用越顺”。核心关键词会围绕AI、编程助手、TypeScript、93K Star、Markdown展开，但重点在于背后的工程逻辑和实操细节。适合已经用过 AI 编程助手、但被它坑过的开发者；也适合刚开始接触、想少走弯路的同学。读完你至少能拿到三样东西：一套约束 AI 的工程框架、一份可直接抄的配置思路、以及一堆我踩过的坑。

2. 为什么 TypeScript 是 AI 编程助手的“天然护栏”

2.1 类型系统就是给 AI 的“合同”

AI 编程助手最大的问题是它不知道你的意图边界。你说“帮我加个用户信息”，它可能给你返回一个对象，也可能返回一个数组，还可能返回一个 Promise。在 JavaScript 里，这些都能跑，但跑起来之后你才发现不对。TypeScript 的价值在于：类型定义本身就是一份可执行的合同。

当你把interface User { id: number; name: string; email: string }写清楚之后，AI 生成代码时就有了明确的靶子。它知道id必须是数字，name必须是字符串，不能随便塞个null进去。这听起来很基础，但实际用起来差别巨大。我做过对比：同一个需求，在纯 JS 项目里让 AI 生成，平均要改 3 到 4 轮才能跑通；在类型定义完整的 TS 项目里，基本 1 到 2 轮就能用。原因很简单——类型错误会在编译期暴露，而不是等到运行时才炸。

更深一层，TypeScript 的类型系统还能表达业务约束。比如你用联合类型type Status = 'pending' | 'active' | 'disabled'，AI 就知道这个字段只能取这三个值，不会给你生成'unknown'或者'deleted'。这种约束在 AI 编程场景下特别值钱，因为 AI 最擅长的就是“合理但错误”的发挥。

2.2 93K Star 项目背后的工程哲学

标题里提到的“93K Star”，在 TypeScript 圈里能到这个量级的项目屈指可数。这类项目通常有一个共同特征：它们不是靠功能堆砌赢的，而是靠工程约束赢的。TypeScript 本身、以及围绕它构建的很多工具链，核心思路都是一致的——用显式的规则替代隐式的默契。

这个哲学放到 AI 编程助手上，就是一句话：不要指望 AI 猜对你的意图，要把意图写成它必须遵守的规则。规则可以是类型定义、可以是 ESLint 配置、可以是目录结构约定、也可以是 Markdown 格式的提示词模板。规则越明确，AI 的发挥空间越可控，产出质量越稳定。

我见过太多团队用 AI 编程助手的方式是“随口一问”，然后抱怨结果不好。这就像你请了个外包，不给需求文档、不给接口定义、不给代码规范，然后怪人家写得烂。TypeScript 圈这套东西之所以“硬”，就是因为它把“给需求”这件事工程化了。

2.3 Markdown 在 AI 协作里的隐藏价值

热词里出现了大量 Markdown 相关的内容：Markdown 语法、Markdown 表格、Markdown 转 Word、Markdown 数学公式插件等等。很多人觉得 Markdown 只是写文档用的，但在 AI 编程助手场景下，Markdown 是人和 AI 之间最自然的“中间语言”。

原因有三点。第一，Markdown 结构清晰，标题、列表、代码块、表格都有明确语义，AI 解析起来比纯文本准确得多。第二，Markdown 可以直接嵌入代码块，并且能标注语言类型，AI 生成代码时能直接对应。第三，Markdown 的表格特别适合表达参数对照、类型映射、错误码说明这类结构化信息，而这些恰恰是 AI 编程时最需要的上下文。

我自己的做法是：每个模块维护一份CONTEXT.md，里面用 Markdown 写清楚这个模块的职责、对外接口、类型定义、常见错误。AI 编程助手在生成代码前先读这份文件，产出质量会有肉眼可见的提升。这不是玄学，而是把隐式知识显式化的过程。

3. 核心细节拆解：怎么把 AI 关进 TypeScript 的笼子

3.1 类型声明文件：给 AI 的“字典”

TypeScript 的.d.ts声明文件，在 AI 编程场景下是一个被严重低估的工具。很多人只在引入第三方库时才写.d.ts，但其实你可以为项目内部的模块也写声明文件，专门给 AI 看。

具体做法是：在types/目录下，为每个核心模块写一份精简的声明文件，只保留对外暴露的类型和函数签名，不包含实现细节。比如：

// types/user.d.ts export interface User { id: number; name: string; email: string; status: 'pending' | 'active' | 'disabled'; createdAt: Date; } export function getUserById(id: number): Promise<User>; export function updateUserStatus(id: number, status: User['status']): Promise<void>;

这份文件的作用是：当 AI 需要生成调用代码时，它不需要读整个实现文件，只需要读这份声明就能知道“怎么调、传什么、返回什么”。上下文窗口是有限的，声明文件就是给 AI 的压缩包。

注意：声明文件要定期同步，否则 AI 会按过时的签名生成代码，反而更乱。我的习惯是每次改完接口，顺手更新.d.ts，当成提交前检查项。

3.2 用 interface 继承表达业务层级

热词里有人问“TypeScript interface 怎么继承”，这个问题在 AI 编程场景下特别关键。因为继承关系是 AI 理解业务层级的重要线索。

举个例子，你有BaseEntity、User、AdminUser三个接口。如果写成平铺的三个独立接口，AI 可能不知道它们之间的关系，生成代码时容易重复定义字段。但如果写成继承：

interface BaseEntity { id: number; createdAt: Date; updatedAt: Date; } interface User extends BaseEntity { name: string; email: string; } interface AdminUser extends User { permissions: string[]; level: number; }

AI 就能清楚知道：AdminUser包含User的所有字段，User又包含BaseEntity的所有字段。生成代码时，它不会在AdminUser里重复写id和name，而是直接复用。继承关系越清晰，AI 的重复劳动越少，出错概率越低。

3.3 静态继承与重写：给 AI 的“行为模板”

热词里还有“typescript static 继承 重写”，这涉及到类层面的约束。在 AI 编程场景下，抽象类和静态方法是最好的行为模板。

比如你有一个BaseService抽象类，定义了find、create、update、delete四个抽象方法。然后UserService继承它，实现具体逻辑。当 AI 需要生成一个新的OrderService时，它只要看到BaseService的定义，就知道必须实现这四个方法，而且签名是固定的。

abstract class BaseService<T> { abstract find(id: number): Promise<T>; abstract create(data: Partial<T>): Promise<T>; abstract update(id: number, data: Partial<T>): Promise<T>; abstract delete(id: number): Promise<void>; } class UserService extends BaseService<User> { async find(id: number): Promise<User> { /* ... */ } async create(data: Partial<User>): Promise<User> { /* ... */ } async update(id: number, data: Partial<User>): Promise<User> { /* ... */ } async delete(id: number): Promise<void> { /* ... */ } }

这种模式的好处是：AI 不需要从零推理，只需要填空。填空比创作简单得多，出错概率也低得多。我实测下来，用抽象类约束之后，AI 生成的新 Service 类基本一次就能通过类型检查。

3.4 Markdown 提示词模板：把“随口一问”变成“按单点菜”

前面说了 Markdown 是人和 AI 的中间语言，具体怎么用？我的做法是维护一套 Markdown 格式的提示词模板，放在项目根目录的prompts/文件夹里。每个模板针对一类任务，比如“新增 API 接口”、“写单元测试”、“重构函数”。

模板结构大致如下：

## 任务类型 新增 API 接口 ## 上下文 - 模块：user - 相关类型：见 types/user.d.ts - 代码规范：见 .eslintrc.js ## 要求 1. 使用 async/await，不用回调 2. 错误统一抛 AppError 3. 返回值必须符合 User 接口 4. 必须写 JSDoc 注释 ## 示例 （附一个已有接口的代码作为参考）

这份模板的作用是把隐式要求显式化。你不用每次跟 AI 重复“记得写注释”、“记得用 async”，模板里已经写死了。AI 拿到这份模板，产出质量会稳定很多。而且模板本身是 Markdown，可以直接提交到 Git，团队共享。

提示：模板不要写太长，控制在 200 行以内。太长了 AI 会抓不住重点，反而适得其反。我的经验是，核心要求不超过 5 条，示例代码不超过 50 行。

4. 实操过程：从零搭一套 AI 友好的 TypeScript 工程

4.1 目录结构设计：让 AI 一眼看懂

AI 编程助手对目录结构非常敏感。一个清晰的目录结构，能让 AI 快速定位到相关文件，减少“翻错文件”的概率。我推荐的目录结构如下：

project/ ├── src/ │ ├── types/ # 类型定义，AI 优先读这里 │ ├── services/ # 业务逻辑 │ ├── controllers/ # 接口层 │ ├── utils/ # 工具函数 │ └── index.ts ├── prompts/ # Markdown 提示词模板 ├── tests/ # 测试文件 ├── CONTEXT.md # 项目整体上下文 └── tsconfig.json

关键点在于types/和prompts/这两个目录。types/放所有对外暴露的类型声明，prompts/放提示词模板。AI 在生成代码前，先读CONTEXT.md了解项目全貌，再读types/了解数据结构，最后读prompts/了解任务要求。三步走下来，AI 的产出基本不会跑偏。

4.2 tsconfig 配置：把严格模式拉满

TypeScript 的tsconfig.json里有一堆严格模式选项，很多人为了省事会关掉一些。但在 AI 编程场景下，严格模式是你的朋友，不是敌人。因为严格模式能在编译期抓住 AI 生成的错误，而不是等到运行时。

我的推荐配置：

{ "compilerOptions": { "strict": true, "noImplicitAny": true, "strictNullChecks": true, "noUnusedLocals": true, "noUnusedParameters": true, "noImplicitReturns": true, "noFallthroughCasesInSwitch": true, "exactOptionalPropertyTypes": true } }

这些选项的作用是：noImplicitAny禁止 AI 偷懒用any，strictNullChecks强制 AI 处理null和undefined，noUnusedLocals防止 AI 生成无用变量。实测下来，开了这些选项之后，AI 生成的代码质量会明显提升，因为它没法糊弄。

注意：严格模式会让初期开发变慢，因为 AI 生成的代码经常报错。但这是好事——报错在编译期，比在线上炸强一万倍。我自己的项目里，严格模式全开，AI 生成的代码平均要改 1.5 轮，但改完之后基本没有运行时类型错误。

4.3 ESLint + Prettier：统一 AI 的代码风格

AI 生成的代码风格往往和项目现有风格不一致。有的用单引号，有的用双引号；有的加分号，有的不加；有的缩进 2 空格，有的缩进 4 空格。这些细节单独看无所谓，但混在一起就很乱。

解决办法是配置 ESLint 和 Prettier，并且把配置文件也纳入 AI 的上下文。具体做法是在提示词模板里加一条：“代码风格必须符合 .eslintrc.js 和 .prettierrc 的配置”。AI 读到这条之后，会主动对齐风格。

我的 ESLint 配置里会特别加几条针对 AI 的规则：

module.exports = { rules: { 'no-explicit-any': 'error', 'no-unused-vars': 'error', 'prefer-const': 'error', 'no-var': 'error', 'eqeqeq': ['error', 'always'], } };

no-explicit-any这条特别重要，因为 AI 最喜欢用any来绕过类型检查。把它设成 error，AI 就没法偷懒了。

4.4 单元测试：给 AI 的“验收标准”

AI 生成的代码对不对，光看类型不够，还得跑测试。我的做法是：每个核心函数都先写测试，再让 AI 写实现。这叫“测试驱动 AI 编程”。

具体流程是：

1. 我先写一个测试文件，定义输入和期望输出
2. 把测试文件作为上下文，让 AI 生成实现代码
3. 跑测试，如果不过，把错误信息反馈给 AI，让它修
4. 循环直到测试通过

这个流程的好处是：AI 有了明确的验收标准。它不需要猜你想要什么，测试文件已经写清楚了。而且测试本身也是文档，后续维护时能快速理解函数行为。

// tests/user.test.ts import { getUserById } from '../src/services/user'; test('getUserById returns user with correct fields', async () => { const user = await getUserById(1); expect(user.id).toBe(1); expect(user.name).toBeDefined(); expect(user.status).toMatch(/pending|active|disabled/); });

这份测试文件就是给 AI 的“合同”。它生成的getUserById必须满足这些断言，否则测试不过。

5. 常见问题与排查技巧实录

5.1 AI 生成的代码类型对不上怎么办

这是最常见的问题。AI 生成的代码看起来没问题，但一编译就报类型错误。排查思路如下：

我的经验是：类型对不上，90% 是上下文没给够。AI 不是不会写类型，而是不知道你要什么类型。把类型定义写清楚，问题基本就解决了。

5.2 AI 改一个地方崩三个地方怎么防

这是“越帮越乱”的典型表现。AI 改了一个函数，结果调用这个函数的三个地方全挂了。防这个问题的核心是控制改动范围。

具体做法：

• 让 AI 改代码前，先让它列出所有受影响的文件
• 用 TypeScript 的“查找引用”功能，确认影响范围
• 改完之后，跑全量测试，不要只跑单个测试
• 如果影响范围太大，拆成多次小改动

我自己的习惯是：每次让 AI 改代码，只改一个文件。改完跑测试，过了再改下一个。这样即使出问题，也能快速定位。

5.3 AI 不按项目规范写代码怎么治

AI 不按规范写，通常是因为规范没写下来。你脑子里知道要用 async/await，但 AI 不知道。解决办法是把规范写成 Markdown，放进提示词模板。

我的prompts/coding-standards.md里会写：

## 代码规范 1. 异步操作统一用 async/await，禁止用回调 2. 错误处理统一用 try/catch + AppError 3. 所有导出函数必须写 JSDoc 4. 禁止使用 any，必要时用 unknown 5. 变量命名用 camelCase，常量用 UPPER_SNAKE_CASE

这份文件每次生成代码前都作为上下文传给 AI。实测下来，遵守率能从 60% 提升到 90% 以上。

5.4 Markdown 上下文太长导致 AI 抓不住重点

Markdown 文件写太长，AI 会“迷失”在细节里。解决办法是分层组织：

• CONTEXT.md只写项目整体架构，不超过 100 行
• 每个模块的README.md写模块细节，不超过 200 行
• 提示词模板只写当前任务相关的内容，不超过 100 行

AI 生成代码时，只传当前任务需要的 Markdown 文件，不要一股脑全传。上下文越精准，AI 产出越靠谱。

5.5 多 AI 协作时上下文怎么同步

热词里提到“多 AI 协作”，这在复杂项目里确实是个问题。我的做法是：用 Markdown 文件作为共享上下文。每个 AI 助手读同一份CONTEXT.md，写代码时也更新这份文件。这样即使换了一个 AI，它也能快速了解项目现状。

具体流程：

1. AI-A 写完一个模块，更新CONTEXT.md里的模块说明
2. AI-B 接手时，先读CONTEXT.md，了解已有模块
3. AI-B 写新模块时，参考已有模块的类型定义和代码风格

这份CONTEXT.md就是多 AI 协作的“交接文档”。它不需要很详细，但必须准确。

6. 我踩过的坑和最后分享的几个技巧

先说几个我实际踩过的坑。第一个坑是过度依赖 AI 生成类型定义。有段时间我偷懒，让 AI 根据代码反推类型，结果生成的类型和实际业务逻辑对不上，后面改起来更麻烦。后来我改成手写类型定义，AI 只负责实现，问题少了很多。类型定义是业务的抽象，这个抽象必须人来定，AI 定不了。

第二个坑是提示词模板写得太泛。一开始我写“请生成高质量代码”，结果 AI 生成的东西五花八门。后来改成“请生成符合以下 5 条规范的代码”，并且把规范逐条列出来，产出才稳定。提示词要具体，不要抽象。

第三个坑是忽略 Markdown 的表格能力。热词里有“markdown 表格复制”、“markdown 表格转换 excel”，我一开始觉得表格只是展示用的。后来发现，用表格给 AI 描述“字段映射关系”特别高效。比如数据库字段和 API 字段的对应关系，用表格写清楚，AI 生成转换代码时基本不会错。

最后分享几个实用技巧。第一，给 AI 的每个任务都附一个“参考实现”。不用很长，20 行左右就行。AI 看到参考实现，会模仿它的风格和结构，产出质量明显提升。第二，用 Markdown 的引用块标注禁忌。比如> 禁止使用 any，AI 对引用块的敏感度比普通文本高。第三，定期清理上下文。项目跑久了，CONTEXT.md会越来越长，定期删掉过时内容，保持精简。

这套方法我用了大半年，最大的感受是：AI 编程助手不是替代品，是放大器。你的工程约束越强，它放大出来的价值越大；你的工程约束越弱，它放大出来的混乱越多。TypeScript 圈那套“用类型约束行为”的思路，恰好是约束 AI 的最好工具。93K Star 的项目能走到那个位置，靠的不是功能多，而是规则清晰、边界明确。这个道理放到 AI 编程上，一样成立。