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 | disabledAI 就知道这个字段只能取这三个值不会给你生成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): PromiseUser; export function updateUserStatus(id: number, status: User[status]): Promisevoid;这份文件的作用是当 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 BaseServiceT { abstract find(id: number): PromiseT; abstract create(data: PartialT): PromiseT; abstract update(id: number, data: PartialT): PromiseT; abstract delete(id: number): Promisevoid; } class UserService extends BaseServiceUser { async find(id: number): PromiseUser { /* ... */ } async create(data: PartialUser): PromiseUser { /* ... */ } async update(id: number, data: PartialUser): PromiseUser { /* ... */ } async delete(id: number): Promisevoid { /* ... */ } }这种模式的好处是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 偷懒用anystrictNullChecks强制 AI 处理null和undefinednoUnusedLocals防止 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来绕过类型检查。把它设成 errorAI 就没法偷懒了。4.4 单元测试给 AI 的“验收标准”AI 生成的代码对不对光看类型不够还得跑测试。我的做法是每个核心函数都先写测试再让 AI 写实现。这叫“测试驱动 AI 编程”。具体流程是我先写一个测试文件定义输入和期望输出把测试文件作为上下文让 AI 生成实现代码跑测试如果不过把错误信息反馈给 AI让它修循环直到测试通过这个流程的好处是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 生成的代码看起来没问题但一编译就报类型错误。排查思路如下问题现象可能原因解决方法类型不匹配AI 没读到最新的类型定义更新.d.ts文件重新生成缺少字段接口定义不完整补全 interface加必填字段返回类型错误AI 猜错了函数意图在提示词里明确写返回类型用了 any严格模式没开开启noImplicitAny我的经验是类型对不上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它也能快速了解项目现状。具体流程AI-A 写完一个模块更新CONTEXT.md里的模块说明AI-B 接手时先读CONTEXT.md了解已有模块AI-B 写新模块时参考已有模块的类型定义和代码风格这份CONTEXT.md就是多 AI 协作的“交接文档”。它不需要很详细但必须准确。6. 我踩过的坑和最后分享的几个技巧先说几个我实际踩过的坑。第一个坑是过度依赖 AI 生成类型定义。有段时间我偷懒让 AI 根据代码反推类型结果生成的类型和实际业务逻辑对不上后面改起来更麻烦。后来我改成手写类型定义AI 只负责实现问题少了很多。类型定义是业务的抽象这个抽象必须人来定AI 定不了。第二个坑是提示词模板写得太泛。一开始我写“请生成高质量代码”结果 AI 生成的东西五花八门。后来改成“请生成符合以下 5 条规范的代码”并且把规范逐条列出来产出才稳定。提示词要具体不要抽象。第三个坑是忽略 Markdown 的表格能力。热词里有“markdown 表格复制”、“markdown 表格转换 excel”我一开始觉得表格只是展示用的。后来发现用表格给 AI 描述“字段映射关系”特别高效。比如数据库字段和 API 字段的对应关系用表格写清楚AI 生成转换代码时基本不会错。最后分享几个实用技巧。第一给 AI 的每个任务都附一个“参考实现”。不用很长20 行左右就行。AI 看到参考实现会模仿它的风格和结构产出质量明显提升。第二用 Markdown 的引用块标注禁忌。比如 禁止使用 anyAI 对引用块的敏感度比普通文本高。第三定期清理上下文。项目跑久了CONTEXT.md会越来越长定期删掉过时内容保持精简。这套方法我用了大半年最大的感受是AI 编程助手不是替代品是放大器。你的工程约束越强它放大出来的价值越大你的工程约束越弱它放大出来的混乱越多。TypeScript 圈那套“用类型约束行为”的思路恰好是约束 AI 的最好工具。93K Star 的项目能走到那个位置靠的不是功能多而是规则清晰、边界明确。这个道理放到 AI 编程上一样成立。 
长河君 · 2026/10/28 14:25:57 · 阅读 1.2k 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 | disabledAI 就知道这个字段只能取这三个值不会给你生成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): PromiseUser; export function updateUserStatus(id: number, status: User[status]): Promisevoid;这份文件的作用是当 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 BaseServiceT { abstract find(id: number): PromiseT; abstract create(data: PartialT): PromiseT; abstract update(id: number, data: PartialT): PromiseT; abstract delete(id: number): Promisevoid; } class UserService extends BaseServiceUser { async find(id: number): PromiseUser { /* ... */ } async create(data: PartialUser): PromiseUser { /* ... */ } async update(id: number, data: PartialUser): PromiseUser { /* ... */ } async delete(id: number): Promisevoid { /* ... */ } }这种模式的好处是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 偷懒用anystrictNullChecks强制 AI 处理null和undefinednoUnusedLocals防止 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来绕过类型检查。把它设成 errorAI 就没法偷懒了。4.4 单元测试给 AI 的“验收标准”AI 生成的代码对不对光看类型不够还得跑测试。我的做法是每个核心函数都先写测试再让 AI 写实现。这叫“测试驱动 AI 编程”。具体流程是我先写一个测试文件定义输入和期望输出把测试文件作为上下文让 AI 生成实现代码跑测试如果不过把错误信息反馈给 AI让它修循环直到测试通过这个流程的好处是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 生成的代码看起来没问题但一编译就报类型错误。排查思路如下问题现象可能原因解决方法类型不匹配AI 没读到最新的类型定义更新.d.ts文件重新生成缺少字段接口定义不完整补全 interface加必填字段返回类型错误AI 猜错了函数意图在提示词里明确写返回类型用了 any严格模式没开开启noImplicitAny我的经验是类型对不上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它也能快速了解项目现状。具体流程AI-A 写完一个模块更新CONTEXT.md里的模块说明AI-B 接手时先读CONTEXT.md了解已有模块AI-B 写新模块时参考已有模块的类型定义和代码风格这份CONTEXT.md就是多 AI 协作的“交接文档”。它不需要很详细但必须准确。6. 我踩过的坑和最后分享的几个技巧先说几个我实际踩过的坑。第一个坑是过度依赖 AI 生成类型定义。有段时间我偷懒让 AI 根据代码反推类型结果生成的类型和实际业务逻辑对不上后面改起来更麻烦。后来我改成手写类型定义AI 只负责实现问题少了很多。类型定义是业务的抽象这个抽象必须人来定AI 定不了。第二个坑是提示词模板写得太泛。一开始我写“请生成高质量代码”结果 AI 生成的东西五花八门。后来改成“请生成符合以下 5 条规范的代码”并且把规范逐条列出来产出才稳定。提示词要具体不要抽象。第三个坑是忽略 Markdown 的表格能力。热词里有“markdown 表格复制”、“markdown 表格转换 excel”我一开始觉得表格只是展示用的。后来发现用表格给 AI 描述“字段映射关系”特别高效。比如数据库字段和 API 字段的对应关系用表格写清楚AI 生成转换代码时基本不会错。最后分享几个实用技巧。第一给 AI 的每个任务都附一个“参考实现”。不用很长20 行左右就行。AI 看到参考实现会模仿它的风格和结构产出质量明显提升。第二用 Markdown 的引用块标注禁忌。比如 禁止使用 anyAI 对引用块的敏感度比普通文本高。第三定期清理上下文。项目跑久了CONTEXT.md会越来越长定期删掉过时内容保持精简。这套方法我用了大半年最大的感受是AI 编程助手不是替代品是放大器。你的工程约束越强它放大出来的价值越大你的工程约束越弱它放大出来的混乱越多。TypeScript 圈那套“用类型约束行为”的思路恰好是约束 AI 的最好工具。93K Star 的项目能走到那个位置靠的不是功能多而是规则清晰、边界明确。这个道理放到 AI 编程上一样成立。