TRAE SPEC coding实战 - 中文PII脱敏library开发

needn
62 阅读14分钟

引言

笔者入行以来一直从事数据开发和架构工作, 除了大量使用SQL语句之外, 偶尔也会使用Python和C#/Powershell写一些胶水代码处理一些项目的零散任务，可以说是轻代码用户。
随着AI编程的时代vibe coding的到来, 让许多非技术背景的用户也能用代码实现自己的需求。对于我来说，一些原本非专业领域的任务:比如图像处理和前端开发, 以前可能根本不会尝试，现在也会敢于积极挑战。

2025年结识了字节的AI编程助手TRAE，对于习惯了VS Code工作环境的用户来说非常容易上手。其后推出的SOLO模式, 更是包含了强大的Agent能力: 从任务规划到细节设计再到分步协同编码，让以人类开发者主导编程的开发模式转变到了由开发者指挥，由AI主导编程的全新模式。

本文通过一个真实的项目案例来分享我的TRAE的使用经验，复盘整个过程中的主要踩坑记录， 也希望能对大家的AI编程之旅有所启发。

项目背景

实现一套专注于国内个人身份信息(PII)识别与脱敏处理的Library和API。
当前AI大模型虽然能力强大, 但也面临着比以往更严峻的数据安全合规问题。尤其是在企业中, 如果个人信息输入了大模型，那么是否会被用于模型训练？是否可能造成其他意外泄漏？都是极为关键的风险因素。
经过调研发现，目前市场上没有特别符合需求又可以开箱即用的开源工具，因此决定尝试用TRAE来自己动手现实一个。

开发环境

  • OS: Windows 11
  • TRAE CN 3.3.32 Solo
  • LLM: GLM-5/Kimi K2.5
  • Language: Python 3.12

最终成果

已经发布到Github github.com/neednlab/cn…

p1.png p2.png

实战流程

从定义规则开始

在开工前我们首先要明确目标是生产级应用，而不是简易demo。随意的Vibe coding会让AI过度自由发挥，导致之后局面难以控制让人焦头烂额。因此事先把业务需求和技术规范都进行有效约束的SPEC coding才是正确解法。
在TRAE中可以定义2个层面的规则(Rule): 个人规则用于定义TRAE用户使用环境和习惯，全局有效；项目规则用于定义特定项目的规范要求。

我的个人规则

  • 始终使用中文进行回答
  • 我的开发环境系统为Windows 11, 所有命令行任务执行必须使用PowerShell, 禁止使用Linux shell命令
    说明: AI特别喜欢执行Linux Shell命令，Windows下一上来就报错，浪费时间和Token
  • 读写你生成的文本文件时，必须使用UTF-8编码。读取外部输入文件时除外，按照外部文件的正确编码进行读取
    说明: 之前其他项目遇到的坑, 强制UTF-8编码可保证中文Windows环境兼容性(默认GBK编码读取)
  • 关键代码和不容易理解的部分，必须添加代码注释详细说明
    说明: 本次项目过程中, 发现AI编码注释写的不够, 特别追加。TIPS: 如下使用TRAE行内提问编辑功能，可以快速解决简单问题 P3.png

> 我的项目规则**初版**(节选重要部分)

角色说明

  • 你是一位Python编程大师，精通包括Django、Flask、FastAPI在内的各种Python开发框架。
  • 你理解现代Python开发实践、架构模式，并且明白在代码生成中提供完整上下文的重要性。

编码规则(关于PRD，TDD和process在下一章详述)

  • 每次编码前检查以下3个文件, 全面理解项目背景与开发进度, 已顺利展开下一次编码任务

  1. 检查SPEC/PRD.md, 确认项目需求与功能目标
  2. 检查SPEC/TDD.md, 确认项目详细技术设计要求
  3. 检查SPEC/process.md, 确认迄今为止的开发进度与任务分配。并在每次编码任务完成后，将最近一次完成的任务总结后记录到该文件中

Python环境规则

  • 项目使用的Python版本为3.12
  • 统一使用uv project方式进行管理
    说明: 非常重要。否则AI容易直接运行python
  • 安装Python依赖时务必使用uv add命令, 禁止使用uv pip install命令
    说明: 重要。否则AI更习惯使用uv pip命令, 不符合uv最佳实践

Python项目开发规范(节选)

  • 严格遵循根目录下pyproject.toml文件中的[tool.ruff]配置规则进行代码编写，生成代码必须满足 ruff check & ruff format要求
    说明：非常重要。让AI自动执行静态代码检查，并可以自动修复。而不是积压在commit或CI流程中
  • 本地日志统一使用Loguru进行日志文件和控制台打印日志配置，禁止直接print日志信息，禁止直接使用logging模块
    说明：个人觉得好用的python log处理lib，用于代替默认logging模块
  • 配置合理的pytest测试框架，实现端到端测试
  • 编写完备的单元测试并提供恰当的测试上下文
    说明：非常重要。让AI自动生成单元测试并自动运行，开发测试流程一体化，效果丝滑。
  • 使用OpenAPI为API编写文档
    说明：重要。API编写同时同步生成文档

代码未动, 文档先行

有了项目开发规范，还不能急着干活，至少必须搞定以下3份文档。

❶把现有需求和想法梳理成完整的PRD文档(Product Requirements Document), 初步想法可以给到TRAE帮助生成文档。我的PRD节选如下，明确输入输出的需求，脱敏的PII范围和优先级。 P4.png

❷根据PRD文档生成详细的技术设计细节TDD文档(Technical Design Document)。这里我只在简单调研后指定了使用Microsoft Presidio SDK，其他都交给AI发挥，生成的TDD初版看起来不错，只做了略微修改就定稿了。(事实证明, 这里由于前期调研不足埋下了隐患，再后面踩坑部分详细说明) P5.png

下图是TDD初稿 P6.png

❸是定义AI每次完成任务后的摘要记录文档process.md，相当于AI的上下文记忆, 每次让AI记得已经完成了哪些任务，新任务从哪里开始着手。我这次只生成了空的process文档，完全让AI自由发挥。可以看到下图文档节选中AI自动将整个工程划分为了5个Phase，每个Phase完成后用户可以新建任务让AI继续开发下一个Phase。看起来基本符合要求，但更严谨的方法应该是先人工根据任务的难度划分好milestone。 P7.png

根据我制定的规则和SPEC，在5个Phase完成后AI自动执行pytest单元测试， 第一版的项目雏形在3~4个小时内就完工了！接下来还需要人工挑选一些case进行深入的业务逻辑测试，进行一些代码微调和优化就完成了。

整个开发过程可以总结如下

flowchart LR
    %% 节点定义
    Start[定义规则和SPEC] --> PRD[编写PRD]
    PRD --> TDD[编写TDD]
    
    %% AI循环部分
    TDD --> AI_Coding[AI编码]
    AI_Coding --> AI_Check{Process文档}
    
    %% 循环连线
    AI_Check -- 继续循环 --> AI_Coding
    
    %% 后续流程
    AI_Check -- 完成 --> Manual_Review[人工检查微调]
    Manual_Review --> Manual_Test[人工复杂业务逻辑测试]
    Manual_Test --> Release((上线发布))

    %% 样式美化
    style Start fill:#f9f,stroke:#333
    style Release fill:#bbf,stroke:#333
    style AI_Coding fill:#dfd,stroke:#333
    style AI_Check fill:#dfd,stroke:#333

在过程中，我几乎不需要手工修改任何代码。很难想象以前，在不懂NLP，不懂OCR，还没有开发过API的情况下会去主动挑战这样的任务，而如今在TRAE的协同下， 一切都变成了可能。

等等，还没结束...故事还没有那么美好！接下来就要分享下我的主要几个踩坑和优化记录。

谁为架构设计负责？

聊回初版的TDD文档设计架构，实际测试中发现默认的模块虽然能跑，但对于中文词义识别和中文OCR都远未达到生产可用的级别，最后整个开发过程中做了两次大的架构变更。

首先是将spaCy NLP模型(自然语言处理)替换为了百度的PaddleNLP，Tesseract OCR模型替换为了百度的PaddleOCR，Paddle在中文的场景下有显著的精度提升。
其次是再将基于PaddleNLP的LAC分词器提供的NER(命名实体识别，用于识别出一句句子中的"姓名"，"位置"和其他信息)方法替换为更先进的information extraction方法, 进一步提升识别精度。 其中还需要解决各个组件依赖和Windows环境的兼容性问题，花了不少时间进行整体大返工。

从这里引出的教训显然是前期调研不足。过于依赖AI直接给出的设计方案，没有深度探讨和核实。在发现识别精度问题时，回到Chat模式再经过多轮探讨才得到了最终版方案。
AI未必一次性就能给出最佳方案，人永远要为你的架构设计负责，编码前多花功夫，能让后面少走很多弯路。

从SPEC到SKILL

第二个挑战是如何维护SPEC。初始版本看起来很好，但一天后就容易失控。 有几个典型问题如下

  • 每次输入新的提示词让AI干活，TA不一定严格遵守TDD文档进行开发
  • 更改设计方案或修复bug后AI没有更新TDD文档，导致文档与代码不一致
  • process文档中信息杂乱，上下文过长，不一定每次需要读取

经过一番思考，我将原本的SPEC进行了拆分，并使用Anthropic推出的SKILL，通过渐进式披露优化上下文展示。关于如何在TRAE中使用SKILL，可参考SKILL详解 首先我把项目开发规范单独拆出了SPEC/DEV.md，然后在TRAE中创建了2个SKILL: feature_developer和debugger

后记: 本次process文档本身主要还是靠人工审阅修改, 效率不高。回头复盘不难发现流水账形式的process并不合适，因为过期的信息和琐碎的信息容易造成上下文污染。比如初版方案的spaCy的流程保留在process当中，其实已经没有价值，没有必要让AI每次完整地知晓项目完整的来龙去脉。以模块维度维护最新的process可能是更好的处理方式。

主要优化了2点

  1. 强调设计变动必须先更新TDD文档再开工
  2. 让troubleshooting时根本不需要读取PRD和process文档，减少上下文干扰。并且独立生成问题记录issue.md文档; 让普通任务连TDD文档都不需要读取，允许自由发挥

使用Debugger SKILL P8.png

使用feature_developer SKILL P9.png

不使用SKILL P10.png

更新后的规则如下

角色说明

  • 你是一位Python编程大师，精通包括Django、Flask、FastAPI在内的各种Python开发框架。
  • 你理解现代Python开发实践、架构模式，并且明白在代码生成中提供完整上下文的重要性。
  • 你需要在合适的时机调用已掌握的SKILL

Python环境规则

  • 本项目使用的Python版本为3.12
  • 统一使用uv project方式进行管理
  • 安装Python依赖时务必使用uv add命令, 禁止使用uv pip install命令

SKILL定义

name: feature_developer description: 编写新代码开发实现新功能

技能规则

  1. 检查SPEC/PRD.md, 确认项目需求与功能目标，全面理解项目背景与
  2. 检查SPEC/TDD.md, 确认项目详细技术设计要求，全面理解项目当前开发进度, 以顺利展开下一次编码任务
  3. 检查SPEC/process.md, 确认迄今为止的开发进度与任务分配。并在每次编码任务完成后，将最近一次完成的任务总结后记录到该文件中
  4. 必须严格遵守SPEC/TDD.md中定义的技术设计要求进行编码。如果有例外情况必须先与我确认，先更新TDD文档再进行编码
  5. 读取SPEC/DEV.md, 严格遵守其中的项目开发规范

name: debugger description: 用于调试与修复代码问题

技能规则

  1. 检查SPEC/TDD.md, 确认项目详细技术设计要求
  2. 执行修复任务时必须严格遵守SPEC/TDD.md中定义的技术设计要求进行编码。如果有例外情况必须先与我确认，先更新TDD文档再进行代码改写
  3. 读取SPEC/DEV.md, 严格遵守其中的项目开发规范
  4. 全局理解相关代码上下文，制定合理的修复方案
  5. 修复任务完成后，必须更新SPEC/issue.md文件，记录最近一次修复任务的详细信息，包括修复时间(精确到秒)、问题原因、修复方式和修复结果

是时候换个模型

第三个坑出现在测试下图时遇到的打码位置错误，其中有地址信息未被打码。 P11.png

在调试中发现，前期一直在用的GLM-5虽然推理能力卓越，但总是无法准确地"看到"最终的图片处理结果，只能根据OCR返回的坐标进行推测调试，反复花了很多时间也没搞定。 此时在TRAE中可以选择多模态模型通过直接理解图片定位问题。如下图，无需终止任务，从GLM无缝切换到Kimi-K2.5，很快就定位到了问题根因：PaddleOCR的文档预处理（UVDoc模型）时对图像进行了几何校正，但返回的坐标仍然是基于校正后的图像，关闭几何校正可以快速缓解问题。 P12.png

结尾

个人从2025年的自动代码补全，到vibe coding制作快速demo MVP，再到2026年第一次有机会用TRAE体验了一把spec coding来完成实际项目，真切地体会到了AI编程的魔力涌现，而且正在飞速进化。

未来编写每一行代码不再是人类开发者的主要工作。相对地，人工的规则制定、架构设计和代码审查成为保障项目质量的关键。不断探索如何用好工具驾驭AI，才是AI时代的必备技能。 不久前马斯克预测说AI将可以直接生成二进制程序，届时是否能够再一次颠覆业界的游戏规则？有相当多的争议，我觉得还不好说，毕竟世界变化实在太快。

本文抛砖引玉，分享了一次项目实战经验。希望与热爱IT技术与coding的开发者共同探索，学习与前进。

过程中最大的感触，也是我的一个核心观点是: 我认为AI coding本身就是在构建一个Agent
每一次用AI coding写一个项目就等于是在构建一个Agent帮你完成这个工程。这里的Agent，我并非是指像SOLO Coder这样的Agent，而是指AI coding这个过程自身。而SOLO Coder更像是可以被当前正在构建的Agent调用的一个通用Agent。我列了以下的表格将两者进行一个类比

Solo CoderAI coding
目标帮助用户编写任意应用程序帮助你或你的团队编写当下特定的应用程序
Guiding上下文工程编写Solo Coder的系统提示词
关注怎么根据用户指令进行规划 -> 编码 -> 测试 -> 反思 -> 修正		你的每次指令(User Prompt) -> 关注做什么
编写Rule，SPEC -> 通常不关心具体怎么做，但提出规则和注意事项，给定约束
Informational上下文工程处理任务内的短期记忆，跨任务的长期记忆
定义如何合理检索代码库和用户文档(RAG)，如何搜索外部文档		定义必须的外挂知识库，Skill的reference
定义AI的process进度文档
Actionable上下文工程调用内置或用户提供的工具(MCP)/Skill
编写必备的内置工具		召唤Solo Coder或其他Agent
配置合理的MCP server/SKILL
avatar
文章
阅读
粉丝