1. 项目概述:当AI助手开始“说”一种精确的语言

如果你和我一样,长期使用Claude Code、Cursor或者GitHub Copilot这类AI编程助手,你一定经历过这种挫败感:你精心编写了系统提示词,告诉它“代码要整洁”、“确保充分测试”,但每次执行的结果都像开盲盒。有时候它确实加了测试,有时候又忘了;你说“整洁”,它可能理解为格式化代码,也可能理解为删除多余注释,甚至可能什么都不做。这种基于自然语言的模糊指令,让AI的“理解”充满了随机性,也让代码生成的质量变得不可预测。

这正是TRUGS Agent要解决的核心痛点。它不是一个传统的SDK,也不是一个运行时框架,而是一个 形式化指令语言 。你可以把它理解为一套给AI编程助手使用的“机器语言”或“协议”。这套语言只有190个单词,但每个单词都有且仅有一个明确的含义,每一条指令都可以编译成一个可验证的图结构。它的目标很简单:让你的AI助手停止“解读”模糊的英文,开始“执行”精确的指令。

想象一下,你不再需要写“请确保代码质量”,而是写“AGENT SHALL VALIDATE ALL CODE SUBJECT_TO INTERFACE schema”。前者是建议,后者是命令。前者可能被忽略,后者则可以被一个独立的验证器( tools/validate.py )检查是否被正确执行。这就是从“概率性遵从”到“确定性执行”的转变。对于追求工程确定性和可重复性的开发者来说,这无疑是一个极具吸引力的思路。接下来,我将带你深入拆解TRUGS Agent,看看它如何工作,以及如何将它集成到你的日常开发流程中。

2. 核心设计思路:从模糊提示到可验证指令图

2.1 问题的本质:自然语言的“歧义税”

我们与AI助手交互的现状,本质上是在支付一笔高昂的“歧义税”。自然语言是人类交流的瑰宝,但它充满了上下文依赖、隐喻和未言明的假设。当我们将它用于给机器(即便是大语言模型这样的高级机器)下达精确指令时,问题就暴露无遗。

以一个常见的 .cursorrules 文件内容为例:

- 编写易于维护的代码。
- 为公共函数添加详细的文档字符串。
- 进行充分的单元测试。

这三条指令每一条都存在问题。“易于维护”的标准是什么?是代码行数、圈复杂度,还是模块化程度?“详细的文档字符串”要详细到什么程度?参数、返回值、异常,还是也要包含示例?“充分的单元测试”的覆盖率目标是多少?需要模拟哪些外部依赖?

AI模型会基于其训练数据中的统计模式来“猜测”你的意图。不同的模型、甚至同一模型的不同调用,都可能产生不同的解读。这导致开发过程充满了不确定性,你无法在代码生成前就确信AI会产出符合你所有隐含标准的结果,更无法在事后进行自动化的合规性审计。

2.2 TRUG/L的解决方案:定义一门极简的领域特定语言

TRUGS Agent的创造者选择了一条截然不同的路径:与其让AI去费力理解模糊的自然语言,不如我们人类稍微“屈尊”,使用一门为指令清晰性而设计的语言——TRUG/L。

这门语言的设计哲学深受形式化方法和法律文书的影响:

  1. 词汇封闭 :整个语言只有190个单词。这强制了概念的精确性和一致性。例如,“VALIDATE”这个词在TRUG/L中有其特定的操作语义,不会与“CHECK”或“VERIFY”混淆。
  2. 语法确定 :句子结构简单、固定,旨在消除解析歧义。典型的指令遵循“主体 + 操作 + 对象 + 约束”的结构。
  3. 语义可编译 :每一条TRUG/L语句都可以被无损地编译成一个图数据结构(TRUG Graph)。这个图由节点(实体,如AGENT, CODE, TEST)和边(关系,如SHALL, SUBJECT_TO)组成。

这种设计带来了几个关键优势:

  • 无歧义 :每个句子只有一种解释。
  • 可验证 :因为指令被编译成了结构化的图,我们可以编写程序(如 validate.py )来检查生成的代码或开发行为是否满足了图中定义的所有约束。
  • 可组合 :简单的指令图可以组合成复杂的开发工作流。
  • 与工具无关 :TRUG/L是纯文本,可以被任何能读取文本的LLM工具(Claude Code, Cursor, Copilot)使用,不绑定任何特定运行时。

2.3 核心架构:文件、模型与验证器的三方协作

TRUGS Agent的架构非常简洁,体现了“Unix哲学”——每个工具只做好一件事,并通过文本进行协作。

[你的LLM工具] --读取--> [AGENT.md (TRUG/L指令集)]
[你的LLM工具] --生成--> [TRUG/L语句]
[TRUG/L语句] <--编译/反编译--> [TRUG图 (JSON)]
[TRUG图] --被检查--> [validate.py (验证器)]
[验证器] --通过/失败--> [反馈给开发者]
  1. 指令源 ( AGENT.md ) :这是你项目的“宪法”。你在这里用TRUG/L语言定义所有AI助手必须遵守的规则。这个文件通常被重命名为或链接到你的AI工具能识别的配置文件,如 CLAUDE.md .cursor/rules/ 下的文件。
  2. LLM工具 :Claude Code、Cursor等工具在分析你的代码库和请求时,会读取 AGENT.md 。它们被“训练”或提示去理解TRUG/L,并在其思考过程中应用这些规则,最终在输出代码或建议时,也可能生成结构化的TRUG/L语句作为其决策的“理由”。
  3. 验证器 ( tools/validate.py ) :这是一个独立的Python脚本。它的作用是充当“最高法院”。它可以解析AI工具生成的TRUG图(或直接分析代码库),并依据 AGENT.md 中定义的规则(以及TRUG/L语言内置的16条CORE规则)进行校验。例如,如果规则要求“每个函数必须有测试记录”,验证器就会扫描代码,检查是否每个函数都有对应的测试文件或测试用例标记。

这个三角关系构成了一个闭环:人类用精确语言定义规则,AI在规则内创作,机器自动校验AI的产出是否符合规则。这极大地提升了AI辅助开发的可控性和可靠性。

3. 快速上手指南:零依赖集成到现有项目

TRUGS Agent号称“零安装”,这并不是营销话术,而是由其设计模式决定的。它不提供需要 pip install 的库来劫持你的运行时,而是提供内容文件供你复制。这是最轻量、侵入性最小的集成方式。

3.1 基础集成:只需一个文件

对于大多数想尝鲜的开发者,从单个文件开始就够了。

操作步骤:

  1. 获取核心指令文件 :你有两种方式。

    • 克隆整个仓库(推荐,便于后续探索其他组件)
      git clone https://github.com/TRUGS-LLC/TRUGS-AGENT.git
      cp TRUGS-AGENT/AGENT.md /your/project/path/CLAUDE.md
      
    • 仅下载核心文件(最快捷)
      # 使用curl直接下载
      curl -o CLAUDE.md https://raw.githubusercontent.com/TRUGS-LLC/TRUGS-AGENT/main/AGENT.md
      # 或者使用wget
      wget -O CLAUDE.md https://raw.githubusercontent.com/TRUGS-LLC/TRUGS-AGENT/main/AGENT.md
      
  2. 重命名与放置 :将 AGENT.md 复制到你的项目根目录,并重命名为你的AI工具所识别的文件名。常见的有:

    • CLAUDE.md (适用于Claude Code)
    • .cursorrules (适用于Cursor)
    • 对于GitHub Copilot,你可能需要将其内容融入仓库根目录的 .github/copilot-instructions.md 或类似的提示文件中。
  3. 初步验证 :现在,当你用AI工具打开这个项目时,它就会读取这些TRUG/L规则。你可以尝试让它生成一个函数,观察其行为是否开始遵循更严格的模式(比如主动询问接口规范或生成测试桩)。

注意 :仅仅复制 AGENT.md 文件,AI工具可能不会立即“理解”TRUG/L。你通常需要给AI一个初始提示,例如在对话开始时说:“请参考项目根目录下的 CLAUDE.md 文件中的TRUG/L规则来指导所有代码生成任务。” 对于Cursor,其规则文件是自动加载的。

3.2 为Cursor用户定制的集成

Cursor对TRUGS Agent有原生支持,集成体验更流畅。

操作步骤:

  1. 克隆仓库后,你会发现一个 .cursor 目录。
  2. 将这个 .cursor 目录整个复制到你的项目根目录。
    cp -r TRUGS-AGENT/.cursor /your/project/path/
    
  3. 这样,Cursor会自动加载 .cursor/rules/trugs-agent.mdc 文件中的规则。你无需再做任何配置,Cursor在分析你的项目时就会应用TRUG/L的约束。

3.3 安装验证工具链(可选但推荐)

虽然核心是零依赖的,但如果你想使用更强大的验证、图操作等功能,可以安装官方的工具包 trugs-tools

操作步骤:

pip install trugs-tools

安装后,你会获得一个统一的 tg 命令行工具。它功能非常丰富:

tg --help  # 查看所有命令,包含36个操作,归在21个顶级命令和3个子命名空间下

常用命令示例:

  • tg validate my_graph.trug.json :验证一个TRUG图文件。
  • tg ls folder.trug.json :列出图文件中的所有节点。
  • tg check . :检查当前目录的文件系统与TRUG图是否一致。

关于旧版包的说明 :请注意,PyPI上存在的 trugs-agent 包(版本1.2.0)已被冻结,它包含的是1.0版之前的旧模板,且不再更新。 要获取最新内容,唯一推荐的方式就是 git clone 本仓库。 这是一个重要的避坑点,避免使用了过时且不兼容的旧规范。

4. TRUG/L语言深度解析与实战编写

理解了理念和架构后,我们来深入看看TRUG/L这门语言本身。编写 AGENT.md 就是编写一份机器可读的“开发契约”。

4.1 语法与核心词汇示例

TRUG/L的语句通常包裹在 <trl> 标签内,以示其是正式指令。让我们拆解一个复杂点的例子:

<trl>
AGENT SHALL GENERATE FUNCTION IMPLEMENTATION SUBJECT_TO INTERFACE api_spec.
AGENT SHALL REQUIRE RECORD unit_test FOR EACH GENERATED FUNCTION.
AGENT SHALL_NOT COMMIT CODE CONTAINING PATTERN “TODO” OR “FIXME”.
AGENT MAY OPTIMIZE PERFORMANCE IF OPERATION latency EXCEEDS 100ms.
</trl>

词汇解析:

  • AGENT : 指代执行任务的AI助手。
  • SHALL : 必须 。这是最强的约束,意味着如果不满足就是违规。
  • SHALL_NOT : 禁止 。硬性禁令。
  • MAY : 可以 。表示允许但非必须。
  • GENERATE, REQUIRE, COMMIT, OPTIMIZE : 操作动词 。每个都在TRUG/L词汇表中有精确定义。例如, REQUIRE 意味着必须存在且可验证,而不仅仅是“建议有”。
  • SUBJECT_TO : 依赖于 。建立约束关系, IMPLEMENTATION 必须符合 api_spec
  • FOR EACH : 量化关系 。表示规则适用于集合中的每一个元素。
  • PATTERN “TODO” : 模式匹配 。检查代码中是否包含特定字符串模式。

从自然语言到TRUG/L的转换:

  • 模糊指令:“记得写测试。”
  • TRUG/L指令: AGENT SHALL REQUIRE RECORD test FOR EACH FUNCTION.
  • 模糊指令:“代码要符合PEP 8。”
  • TRUG/L指令: AGENT SHALL FORMAT ALL PYTHON_CODE SUBJECT_TO STANDARD pep8. (假设 pep8 被定义为一个标准节点)

4.2 编写你的第一个AGENT.md文件

你不必从零开始。最好的方式是复制官方的 AGENT.md ,然后根据你的项目需求进行裁剪和增补。下面是一个为Python后端API项目定制的简化示例:

# Project-Specific TRUG/L Directives

## Core Development Principles
<trl>
AGENT SHALL PRESERVE CONSISTENCY WITH EXISTING code_style.
AGENT SHALL_NOT INTRODUCE SECURITY vulnerability.
AGENT SHALL DOCUMENT ALL PUBLIC_API INTERFACE.
</trl>

## Code Generation Rules
<trl>
AGENT SHALL GENERATE FUNCTION IMPLEMENTATION SUBJECT_TO INTERFACE openapi_spec.
AGENT SHALL REQUIRE RECORD pytest FOR EACH GENERATED FUNCTION.
AGENT SHALL MOCK EXTERNAL SERVICE IN TEST.
AGENT SHALL_NOT DUPLICATE LOGIC WITH EXISTING FUNCTION.
</trl>

## Commit & Quality Gates
<trl>
AGENT SHALL VALIDATE CODE WITH TOOL black BEFORE COMMIT.
AGENT SHALL VALIDATE CODE WITH TOOL mypy BEFORE COMMIT.
AGENT SHALL_NOT COMMIT CODE IF ANY TEST FAILS.
AGENT SHALL_ENSURE COMMIT_MESSAGE REFERENCES issue_tracker ID.
</trl>

## Definitions (Optional but helpful for clarity)
<!-- 这里可以定义一些项目中特定的节点类型和关系 -->
- `openapi_spec`: The OpenAPI 3.0 specification file at `./api/openapi.yaml`.
- `code_style`: Follows the Black formatter and isort for imports.
- `security vulnerability`: Includes SQL injection, XSS, hard-coded secrets, etc.

编写心得:

  1. 由粗到细 :先从最高层的原则开始(如安全、一致性),再深入到具体的生成规则和提交门禁。
  2. 定义术语 :在 Definitions 部分或用注释定义自定义节点(如 openapi_spec ),这能极大提高指令的清晰度,也帮助AI理解上下文。
  3. 保持可验证性 :每写一条规则,都思考一下“ validate.py 能否自动检查这条规则?” 例如,“禁止重复逻辑”可能难以自动化验证,但“每个函数必须有pytest记录”就很容易检查。
  4. 迭代优化 :不要指望第一次就写出完美的 AGENT.md 。在实际使用中,观察AI在哪里“犯错”或产生歧义,然后补充或修正你的TRUG/L指令。

4.3 验证指令是否被遵循

编写完指令后,关键的一步是验证。TRUGS Agent仓库自带了一个简单的验证脚本。

基本验证:

# 假设AI生成代码时也生成了一个描述其决策的TRUG图文件 decision.trug.json
python tools/validate.py decision.trug.json

# 或者,让验证器扫描整个项目,检查是否违反AGENT.md中的规则
python tools/validate.py --all /path/to/your/project

验证器会依据16条内置的CORE规则(如“SHALL指令必须被满足”)和你在 AGENT.md 中定义的规则进行检查,并输出通过或失败的报告。

集成到CI/CD: 为了真正发挥威力,你应该将TRUG验证集成到你的持续集成流水线中。例如,在GitHub Actions中:

- name: Validate TRUGS Compliance
  run: |
    python tools/validate.py --all .

这样,任何不符合TRUG/L规则的代码提交都会导致CI失败,从而在合并前阻止不合规的AI生成代码进入主分支。

5. 进阶组件:构建你的LLM增强开发环境

TRUGS Agent远不止一个 AGENT.md 文件。其仓库是一个模块化工具箱,其他组件可以像乐高一样与核心指令语言组合,解决更复杂的问题。理解这些组件能帮助你构建一个真正强大的、由AI辅助但由规则驱动的开发系统。

5.1 FOLDER/:机器可读的项目索引

是什么? 一个将你的项目目录结构自动转换为TRUG图的工具/规范。生成的 folder.trug.json 文件用节点表示文件夹/文件,用边表示包含、引用等关系。

有什么用? 让LLM真正“理解”你的项目结构,而不仅仅是看到一堆文件列表。LLM可以查询这个图,例如“找到所有依赖于 utils.py 的文件”,从而做出更准确的修改。

如何使用?

  1. 复制 FOLDER/ 目录下的工具或借鉴其思路。
  2. 运行脚本生成你项目的 folder.trug.json
  3. AGENT.md 中的指令与文件夹节点关联。例如: AGENT SHALL PLACE NEW TEST_FILE UNDER node tests/

5.2 AAA/:九阶段开发协议

是什么? 一个结构化的开发工作流,将任务分解为Plan(计划)、Code(编码)、Audit(审计)三个高阶阶段,每个阶段再细分为三个子阶段,共九个阶段。每个阶段都有明确的输入、输出和验收标准。

有什么用? 强制你和AI进行有纪律的、分阶段的开发,避免一蹴而就。特别适合复杂功能或重构任务。AI在每个阶段只关注该阶段的目标。

实战流程:

  1. A1 (Analyze) :分析需求,输出功能规格TRUG图。
  2. A2 (Architect) :设计架构,输出组件关系图。
  3. A3 (Accept) :定义验收测试用例。
  4. C1 (Construct) :实现核心逻辑。
  5. C2 (Connect) :集成组件。
  6. C3 (Confirm) :通过单元测试。
  7. D1 (Debug) :系统测试与调试。
  8. D2 (Document) :编写文档。
  9. D3 (Deliver) :最终审查与提交。

你可以要求AI:“我们现在处于AAA协议的A1阶段,请根据需求文档生成分析图。” 这比单纯说“分析一下这个需求”要清晰得多。

5.3 MEMORY/:跨会话持久化上下文

是什么? 解决LLM“金鱼记忆”问题的方案。它将重要的决策、设计理由、待解决的问题以TRUG图的形式持久化到磁盘( memory.trug.json )。

有什么用? 在新的对话会话中,AI可以“加载记忆”,回忆起之前为什么选择某个库、某个接口设计是如何达成的,从而保持决策的一致性。

操作示例:

  • 在解决一个复杂bug后,你可以让AI执行: AGENT SHALL RECORD DECISION reason IN MEMORY FOR issue_#123.
  • 下次会话开始时,你的提示词可以包含: LOAD MEMORY FROM ./memory.trug.json AND CONTEXTUALIZE CURRENT TASK.

5.4 其他组件速览

  • EPIC/ :用于管理多项目或大型特性的组合看板,同样用TRUG图表示,可以追踪特性之间的依赖和状态。
  • TRUGGING/ :鼓励你用TRUG图来描述代码库的架构(微服务、数据流等),创建活的、可验证的架构文档。
  • WEB_HUB/ :一个将网络资源(工具文档、论文、库)索引为TRUG图的知识库,方便AI检索参考。
  • SKILLS/ :提供了19个可组合的“技能”原语(如 SEARCH_CODE , REFACTOR ),可以用来构建更复杂的AI工作流指令。

组合使用建议 :不要试图一次性全部用上。从 AGENT.md 开始,当你遇到“项目结构复杂AI难以理解”时,引入 FOLDER ;当遇到“复杂任务需要分步指导”时,引入 AAA ;当遇到“AI总忘记之前约定”时,引入 MEMORY 。让需求驱动你的工具链演进。

6. 常见问题、排查技巧与生态对比

6.1 实战中可能遇到的问题与解决方案

Q1:我复制了 AGENT.md ,但AI好像完全无视它? A1 :这通常是因为AI工具没有正确加载该文件。

  • 对于Cursor :确保 .cursor/rules/trugs-agent.mdc 文件被正确放置在项目根目录的 .cursor/rules/ 下。重启Cursor IDE有时是必要的。
  • 对于Claude Code :确保文件被命名为 CLAUDE.md 并位于项目根目录。在对话中,你可以显式地提示:“请严格遵守 CLAUDE.md 中的TRUG/L规则。”
  • 通用检查 :尝试在对话中问AI:“你能看到我项目根目录下的 CLAUDE.md 文件吗?请简述里面的核心规则。” 这可以测试文件是否被成功加载。

Q2:TRUG/L规则写得太严格,限制了AI的创造性怎么办? A2 :TRUG/L的设计初衷是消除有害的歧义,而非扼杀所有灵活性。合理使用 MAY (可以)和 SHOULD (应该)而非 SHALL (必须)。将规则分层:

  • 核心层(SHALL) :涉及安全、基础架构、团队规范的原则性问题(如“禁止硬编码密码”、“必须通过类型检查”)。
  • 推荐层(SHOULD) :关于代码风格、最佳实践的指导(如“函数长度应该控制在50行以内”)。
  • 允许层(MAY) :给予AI发挥空间(如“在性能关键处,可以选择使用缓存”)。

Q3: validate.py 检查失败,但我看不懂错误信息。 A3 :验证器的错误信息通常指向TRUG图中的特定节点和边。

  • 步骤1 :找到报错的节点ID或关系类型。
  • 步骤2 :查看生成的TRUG图文件(通常是JSON),定位到出错的部分。
  • 步骤3 :对照 AGENT.md 中的原始指令,检查图结构是否正确地表达了你的意图。常见错误包括节点类型未定义、关系不符合语法、或 SHALL 指令的预期结果节点缺失。
  • 技巧 :使用 trugs-tools 中的 tg visualize decision.trug.json --output graph.png 命令(如果支持)将图可视化,能更直观地发现问题。

Q4:如何为我的技术栈(如Go、Rust、Java)定制TRUG/L词汇? A4 :TRUG/L的190个核心词汇是领域无关的。定制化主要通过“定义”来实现。

  1. AGENT.md 中创建一个 ## Definitions 部分。
  2. 为你技术栈特有的概念定义节点。例如:
    - `go_mod_file`: REFERS TO FILE “go.mod”.
    - `rust_crate`: A COMPILATION UNIT IN RUST.
    - `java_spring_annotation`: PATTERN “@SpringBootApplication”, “@RestController”.
    
  3. 在规则中引用这些自定义节点。例如: AGENT SHALL UPDATE go_mod_file WHEN ADDING NEW_DEPENDENCY.

6.2 与主流AI代理框架的深度对比

在决定是否采用TRUGS Agent时,明确其定位至关重要。它并非要取代LangChain、CrewAI等框架,而是解决一个不同维度的问题。

维度 TRUGS Agent LangChain / CrewAI / Pydantic AI
核心定位 指令语言与协议 。定义AI 应该做什么 规范 编排框架与运行时 。实现AI 如何去做 执行引擎
交互模式 声明式 。你写下“目标状态”(规则),AI负责达成。 命令式/过程式 。你编写代码来调用AI函数、控制流程。
集成复杂度 极低 。复制文本文件即可。无依赖冲突。 中到高 。需要安装Python包,可能引入依赖冲突,需要学习框架API。
可验证性 核心特性 。指令可编译为图,支持静态和动态验证。 较弱 。通常依赖测试和人工审查,提示词本身的符合性难以自动化验证。
供应商锁定 。纯文本协议,任何能读文本的LLM工具都可使用。 。代码绑定特定框架(LangChain链、CrewAI Agent类)。迁移成本高。
适用场景 增强现有AI编码助手 (Cursor, Claude Code),使其行为更确定、可审计。在 严格合规 (如安全、金融)或 大型团队 需要统一AI行为标准时优势明显。 构建复杂的多步骤AI应用 ,如自动化客服、数据分析流水线、研究代理。需要编程来粘合多个模型、工具和逻辑。
心智模型 给AI一本 不可违背的《操作手册》 编写一个 驱动AI的软件程序

简单来说:如果你在用Cursor写代码,但受够了它时好时坏的理解能力,TRUGS Agent是你的解药。如果你在构建一个自动化的内容生成流水线或客服机器人,你需要的是LangChain这类框架。两者甚至可以结合:用TRUG/L来严格规范框架中每个AI节点的行为准则。

6.3 性能与成本考量

  • 性能 :TRUGS Agent本身几乎没有性能开销。主要的开销在于LLM处理稍长的、包含TRUG/L规则的上下文。但这通常可以忽略不计,且换来了输出质量的确定性提升。
  • 成本 :没有直接货币成本。潜在的“成本”是学习和编写TRUG/L规则的时间投入。然而,这项投入会在减少代码返工、提高审查效率、降低缺陷率上获得回报。
  • 学习曲线 :对于开发者,学习190个单词的基础语法很快。真正的挑战在于思维转变——从写模糊提示到写精确指令。这类似于从写注释到写单元测试的转变,初期需要适应,但长期来看能形成更严谨的开发习惯。

TRUGS Agent代表了一种务实而深刻的思想:与其等待AI完全理解人类模糊的意图,不如我们主动迈出一步,使用一种更适合机器处理的精确语言来沟通。它可能不是所有问题的答案,但对于任何受困于AI助手输出不稳定、渴望在AI辅助开发中引入工程纪律的团队和个人来说,它提供了一个极具启发性且立即可用的解决方案。从我个人的试用经验来看,最初编写规则需要一些思考,但一旦规则集稳定下来,它就像给AI戴上了“缰绳”,让天马行空的创造力沿着你设定的高质量轨道奔跑,那种可控感和效率提升是非常显著的。

更多推荐