接下来我们来讲一下CodexAgence.md配置与架构设计。
那这个Agence.md的话其实是Codex在这个规范化编程这一块做的一些整个架构的一个设计。
它系统这个里面定义了一个规范,我们可以在这个Agence.md里面可以把项目的一些实际的一些开发规范,包括我们整个项目的一些结构,
放到这个文件里面
那么在Codex加载的时候
我们去分析整个项目结构的时候
他会优先去读取这个agents.md文件
这样的话
他就相当于了解了我们项目的全局的一些
这个大致的一些情况
所以说这个agents.md的话
其实就是作为一个规范
这个驱动开发的一种方式
通过整个全局的一个说明
包括我们整个目录层级
它的一些关键的一些文件在哪里
比如说像一些文档
我们整个项目的一个架构文档
设计文档 API文档
通过这个agents.md文件
把我们相当于这个代码地图描述了非常清楚
那这个AI就可以快速了解到
我们项目里面的一些重点信息
这样的话
那你让它去生成代码的时候
相当于它已经把你整个项目
大致做了一个了解了
这样他去找文件的时候
他的一个效率就会非常高
速度也非常快
那么Codex他是如何发现
这些个文件的呢
首先的话
他会启动的时候
他会整理出一条本次运行
需要使用的一个指令链
那么他首先会做一个检查
他这个检查的话
是有一个顺序层级的
首先第一层的话叫做全局层
那这个的话
就是在我们的这个Codex主目录里面
有个叫点Codex目录
就是在当前登录用户的这个目录里面
有一个叫点Codex的一个目录
当然我们也可以在环境面量里面
去指定这个Codex Home
通过这个环境面量去指定指定的一个目录
那我们指定之后的话
Codex在运行的时候
它就会把它的一些文件
就是系统的一些文件
默认的会去存放到这个目录里面去
如果大家没有设定的话
它就是在当前登录用户的这个
一个目录下面
有一个叫.codex这么一个目录
那么在这个目录下面的话
我们可以去指定一个叫
agents.overload.md
那么这个的话
就是一个全局的一个agents.md
那么在这个里面的话
我们写的内容
它会优先去读取
要是没有的话
他再会去读取这个agency.md文件
所以说他这个里面就是一个规范啊
首先从最外层去开始去找找这个文件
如果能找到的话就优先使用它
找不到的话再往下一层级去找agency.md
好然后第二个层级叫项目级
比如说啊
我们这个项目里面
我们在项目里面也可以去写这个agency.md
比如说我们整个项目啊
它是什么一个结构
规范是怎么样的
包括它的一些后代命令
有哪些数据库配置
有哪些等等的
这些个内容
我们都可以写到
agents.md里面去
然后的话就是
我们如果在项目层
写了agents.md
但是呢
全局层又没有写的话
它会优先使用
项目层里面的agents.md
去做一个读取
那这里面
它也会去优先去找
agents.overload.md
如果找不到的话
他就会找这个
所以说我们在项目里面写agentsmd
如果又没有配置其他的这个md文件的话
他的优先级这个就是最高
所以这个就是项目层
全局层的话就是比如说啊
大家在本地我开发多个项目啊
我有python的这个项目
有java的项目
如果说你需要所有的这个规范啊
做一个对齐的话
那这里面大家就可以去全局层里面
去把这个agentsmd做一个定义啊
比如说我是作为一个个人开发者
然后他的一个规范是怎么样的
就是所有的项目都是按这个规范来的
按照我个人的一个编码风格来
不管你是什么语言的项目
都得按我这个风格来
这个就比较适合放全局
放项目的话
就是每个项目的一些特定的一些配置
比如说后端项目
那后端项目肯定有一些接口啊
架构设计啊
包括一些数据库脚本啊等等的
那如果是你是个前端项目的话啊
那比如说有这个
npm 包的一个设置
是吧
有 package 点 json
还有一些这个像
vio 的一些酷啊
react 的一些酷啊
是吧
这个就是前端的一些这个层级
包括一些路由配置啊等等啊
那每个项目的话
它的规范也不一样啊
我们用前端跟后端
所以这个项目层里面
肯定是要区分这个agents.md的
这个就比较适用于放到这一层
呃
然后的话
最后啊
如果两个都写了怎么办呢
都写的话
都是他就是都会去读取
然后越靠近当前目录的文件越靠后
所以说他会覆盖前面更通用的一些说明
他就是按照这么一个层形去做覆盖
那空文件的话就会被跳过
合并总大小一旦达到他设定的一个上限的话
这个Codex就不会加入更多的一些文件了
所以说他是有一个上限的
当然这个参数也可以去调
也就是我们整个文档
你也不能放太大了
因为这个的话是Codex
它工作的时候默认会加载的一个文档
如果大家把这个文档做的很大
比如说做一兆是吧
非常大
直接就超过这个上下文了
那这个显然是不太合适的
就是对于首先成本消耗
包括上下文窗口的话
一下子可能就超出去了
所以agents.md里面要写的内容
比如说你是项目层的这个agents.md
一定要写跟项目相关的一些
比如说这个命令啊
是吧
然后工程规范啊
项目结构啊
这是一些非常核心的内容
那么我们就写到这个里面
基本上大概就是100行左右啊
不能太多
太多的话就很容易超过这个上下文线
所以这个是一个细节点啊
那么大家就可以在这个
按照上面我们
就是确认好的一个这个层级啊
你可以在全局层里面啊
就在这个里面去加agency.md
那我们这里的话
主要是带大家在项目里面去讲啊
在项目里我们用了最多的方案
还是在项目里面去加agency.md
所以最外层的这个用户目录下
那个agency.md的话
我们一般来说不会去改
因为我们一般是按项目来去做一个驱动啊
这是实际啊
实践的这个场景
就是在项目里面加agency.md比较多啊
当然大家如果确实有需要的话
你可以去那个里面改啊
那我们盖完之后的话
就是在这个里面
我们会写哪些东西呢
比如说你是做一个前端项目
那你肯定要去写一些这个
NPM的一些命令啊
一些描述是吧
那整个这个项目
他就是去比如说添加一些依赖的时候
需要做一个确认
那这个就是我们针对前端这种项目啊
可以写的一个agency MD
但肯定不会这么简单
我们还可以可以写很多内容
所以说啊
这个里面啊
就大家首先要搞清楚这么一个场景啊
如果说你确实要去写一些全局的这个agents.md的话
那你就写到用户目里面去
如果说你只是做一个这个项目的一个场景的话
你就放到项目的这个agents.md里面去
那么这个agents.md的话
它这个里面的话
我们可以首先在根目录里面去加
然后的话
比如说你还需要做这个覆盖
是吧
你要做覆盖的话
你就可以去创建agents.md
那它就会去覆盖当前的agents.md
那这个就比较适用于
那比如说根目录啊
我加了这个agents.md了
但是呢
在某一些模块下啊
不同因为我们
我们就做项目开发的
大家知道是分模块开发的是吧
那有的模块它是别的小组
那人家别的小组有自己的一套规范
他不想说跟着你规范一起调了
我们有自己的一套规范
所以的话
我们可能在某个模块下面
加一个agency.md.org
这样的话
我们就直接可以去覆盖之前的一个配置
所以这个是比较适合于做一些覆盖的一场景
就当于每一个团队都有自己的一个特色
那并且的话
我们也可以在某个模块去启用这个Codex
然后去做一个执行
OK
这个就是我们可以在不同的模块下面啊
去加这个Agence.md
好
然后的话
就是这里面一个逻辑就是Codex
首先会去报告全局文件
然后再去报告仓库的根目录
最后再去报告
某个模块
比如说像这个支付模块
下面的一些覆盖文件
是吧
那么Codex在搜索的时候
会达到这个当前目录的话
就会停止
所以说尽量应该把覆盖文件
靠在专门
就是按照规范去做一个存储
所以说我们
加了这个模块之后
你就在这个模块下面
直接就放这个MD文件就可以了
所以它是相当于
我们可以在不同的模块下面
就不只是根目录可以讲
不同的服务下面都可以去讲
然后并且的话
我们还可以去自定一些备用文件名
比如说像仓库里面已经在使用其他名字
是吧
那你可以把它加入到这个备用列表里面去
让Codex把它当作说明
什么意思呢
就比如说
你现在有一个团队的这个手册是吧
就是我们所有的项目都按这个手册来操作的
那这个就比较适合于付放全局的这么一个
叫做config.tom文件
这个是Codex
它整个应用的一个配置文件
这个配置文件下是全局的
也就是说你在这个里面
加这个规范之后
整个团队啊
都是按照这个规范去执行
所以这个是一个全局的
一个配置文件
我们可以把它加到这个里面去
也就是大家除了这个agents.md以外
是吧
那你比如说
我不想用agents.md这个文件
这个名称
我想换一个
比如说叫teamgather
那我就放到这个里面去
这个也是OK的
所以说整个一个文件命名的话
就是大家可以很个性化
但只是说你要去做一个配置
多余的做一个配置
你如果不想配置的话
你就用agents.md会方便很多
所以说大家有备用的一些文件需要加载
还是说你就用agents.md里面加载
它都是支持的
它都有这么一个规范
然后如果说你不希望使用不同的配置档的话
比如说某个项目专用的这个自动化账号
可以设置这个codex.home环境变量
那这个里面的话就是
我们可以单独去做一个search
就单独去做一个page
某些场景下面我们就用不同的这个codex.home环境变量就可以了
这个也可以做不同的这个page
然后配置完之后的话
我们怎么样去验证呢
是吧
验证这个到底有没有效果呢
那我们可以去看一下
比如说我现在就在
全局的这个agency.md里面
给大家来看一下
比如说我们在当前用户
这个.codex目录
.codex目录
.codex目录下面有一个agency.md
你看现在我们是什么都没写
是吧
那我们就比如说可以写一下
这是
全局的
配置文件
那就是说比如说
我个人的开发规范
比如说是采用
DDD
就是这种领域驱动的方式
进行
编程
进行这个
功能开发
就是我个人的一个规范
我们写在这个根目录的这个agents点目定里面
然后我
是现在我就切换到这个Codex目录里面
然后我们去这个打开啊
这个我一般建议是用
终端的管理员的方式打开
不然的话他可能会有权限的一些问题
然后切换到底盘
切换到Codex目录啊
然后这里我们就进去啊
说这个Codex
然后你就随便问他啊
就是我们在这个里面加的东西
然后你就问
我个人的开发规范有哪些啊
你就这么来问
然后我们看一下它能不能加载啊
你看
功能开发采用DDD领域驱动啊
所以这个就是
我们放这个应用层是吧
就是所有的项目都会采这个规范啊
就不管你是哪个项目的是吧
那你都要按照我DDD的这个领域驱动的方式
做一些功能开发啊
这是我个人一个小习惯
然后比如说啊
我们现在单独的
我们再建一个项目
比如说这个里面
这个叫什么呢
叫做
test
或者怎么叫project
project2
那我们在这个里面建一个文件
叫做agents
agents.md
是吧
好
然后这个里面啊
我们就给他改一下是吧
加一些特定的一些规范
比如说我们用这个里面的一些规范来定一下啊
我就随便找一个吧
比如说我就
就把这个规范加进去
放到这个规范里面去
然后
就这样
然后我们现在切换到那个木里面去
CD到这个project2
是吧
然后注入codex
然后你就问他
当前项目
开发规范
由
哪些
大家看啊
你看
这个是我自己的项目规范是吧
什么pr
pr前线运行mpm run
lint
这是我个人的一个习惯
然后你看我们刚刚写的那个全局的应用规范
是不是也在啊
这个有限级非常高啊
就是这你不管签哪个项目
它都会有这么一个规范
这个就是我们实际的规范
好
这个就是大家可以自己的去写不同的这个规范
是吧
然后你还可以去创建这个agency.overload的这么一个MD文件
然后我们来做一个覆盖
比如说我们就在这个里面
修改行为时
试一下把这个给覆盖一下
比如说现在是有这么一个
修改的时候需要在docs里面记录是吧
那我现在比如说我现在想做一个覆盖
在uproad里面再加一个东西
把这句话
我的call过来
我现在同样的也是call这个
然后在这个里面
然后我现在把这个覆盖一下
在比如说在logs里面
在logs里面去记录工具的一个变化
记到日志里面去
我们看一下它加载策略是什么
先退出去
然后codex
当前项目开发规范有哪些
嗯他说这个有编码问题
看一下他能不能会帮我们解决这个问题啊
你看是不是覆盖了
我现在这个优先级更高是吧
不管你这里写的是DOC什么的
因为我这个下面
然后这里写了这个重载了
是吧
所以他还是会用这个logs去制写
这个就是叫agents.overload.md
他的一个作用
就是我们想在同一套规范下面
不同团队
不同小组
要单独写一些自己的小规范
要覆盖一些
就是在公司的这个规范基础之上
或者在大团队的规范基础之上
然后再加我们这个
小团队的这么一个规范
那么啊
比如说这个是公司有很多业务线
我支付这个线里面
我有自己的一些规范
这个就比较适合用这个agency.overall的MD
所以这个大家根据自己的情况
去选择不同的这个MD文件啊
好
这个就是我们效果的一个验证
然后包括我们其实也可以去配置一些
这个团队的一些文档啊
这个就根据实际需求去了
调整了啊
基本上我们用在根目里面
配这两个的话
基本上够用啊
就这两个场景
基本上按项目去配差不多了
除非你确实有公司的这个
级别的一些规范是吧
那你可以加到这个里面去啊
这个就是他的一个层级啊
大家首先要搞清楚这个点
呃
然后验证的话
我们刚刚其实也带大家去验证了
当然你也可以去执行一些命令啊
然后去看一下它到底有没有覆盖啊
这个都是OK的
那比如说我们经常可能会出现的一个问题是什么呢
就是大家可以去排查啊
就是哎
有时候会发现它这个到底有没有加载是吧
这个文件里面有没有一些
就什么都没加载啊
就看一下到底什么问题
大家可以执行这个Codex
Status啊
去分析一下
比如说我们在这个里面先退出去
至今Codex status
那它这个里面的话就会进入了
去分析它的一个status
然后我们在这个里面
它可以去分析整个工作区的一个状态
就是比如说它没有加载
那你可以去检查一下
看一下这个里面到底有没有问题
是吧
你看它这里分析出来
就是它不是一个Git仓库啊
所以他在分析有一些这个信息的时候
他可能就会少一些内容
所以他可以得出来
这个到底有没有是不是空目录是吧
是不是空仓库
他可以给你分析出来
然后的话大家会发现啊
就是你有时候那个配置啊
就是你写了
但是他没有生效
这时候大家就要去检查一下
我的上一集到底有没有这个啊
更高层级的一些目录是吧
有一些MD文件
是不是也给它覆盖掉了
那这个里面的话
就是我们要去检查一下
就是你会发现
你加了一个配置之后
它没有生效
但是的话
你的配置加上去了
没问题
但是你一执行
就发现这没生效
那你就可以看一下
上级有没有更高的一些
这个规范
是不是把它给覆盖掉了
这个大家可以去检查一下
就我刚刚提到那几个层级
一个是全局的
还有一个是用户级别的
用户级别就是项目级别的
项目级别的你要看是
有没有agents.overall.md文件啊
所以这个要特别的去检查一下
然后包括一些这个
你加了一些备用文件名了
你会发现他也没有加载
那你就要检查一下
哎路径对不对啊是吧
然后这个配置有没有生效啊
其实大家遇到这个问题之后啊
如果说你确实排查不出来的话
你可以把你的一个配置丢给codex
让他自己去分析
排查到底是哪里出错了
它的分析能力很强的
它一看可能你就知道
你这个确实哪里参数拼的有问题
比如说路径写的有问题
是吧
或者一些其他的参数写的有问题
它马上就可以给你分析出来
这个里面的话
我们可以利用Codex这个分析能力
帮我们去做很多事情
然后包括一些指令被截断了
也就是说大家
你写了一堆东西是吧
写了很多
写了几百行几千行
你发现最后执行的话
可能就识别到了几百行
那这个的话就大家要把这个
有一个参数啊
叫project dockmarks
但是这个参数不是越大越好啊
你改的越大的话
对于token的这个成本消耗也是比较大的
就相当于我们对话都没开始呢
一开始就给你加了一堆内容去了
下到上下往里面去了
这样就会导致我们整个每次对话的时候
成本就会上升
所以agency.md里面绝对不是内容越多越好啊
而是越精简越好
越核心越好
这样的话
因为它的目标
它就是去用来定规范的
你不要把一些
无关紧要的内容
写到agency.md里面去
这样反而可能会
导致这个上下文超长
是吧
或者是它出现截断的这个问题
就明明你写这个指令
你发现它就是没有执行
那是因为它被截断了
都没加载进来
肯定就没法执行
然后包括这个配置
是吧
配置档
就是我们当前
大家会发现
就是你我们已经在这个当前的
用户目录下
这个.codex目里面改了这个agents.md了
你发现他就是不生效
那这时候你可以去看一下
当前你有没有设置过环境变量
把codex这个目录是吧
你给他设置到其他地方去了
所以导致他整个逻辑的方法
就是没有被执行到
这个也是大家需要去确认的
我们要把整个逻辑给他去确认一下
所以这个里面是一个非常关键的点
就是你这些目录你最基本的
你要做一个确认
是吧
那这样就不会出现一些
细节的一些问题
然后是agents.md到底应该怎么来写呢
是吧
那大家可以写哪些内容呢
我这里给他看一个例子
前段项目啊
你看前段项目就是这套规范
大家如果不知道怎么去写的话
其实很简单啊
很简单怎么来干呢
你可以打开这个codex啊
我这个是一个这个插件版的codex啊
你就直接这么跟他说啊
请帮我分析一下当前项目结构
然后输出一份agents.md
当前项目结构和代码规范
然后输出一份agentsmd就完了
就很简单啊
就大家你直接让AI来帮你分析输出一份
然后看他怎么写的
然后你再去参考再去调整是吧
这也是一种学习方式啊
就让AI他肯定比你写的好啊
写的更加的完善
所以你看他怎么写就完事了
但是我这里面已经有了
我就不重新生成了
我只是给大家讲一下这个方法
因为生成这个东西的话
他也要去做各种分析
也比较时间比较久
所以这个大家可以自己去生成
我这个就是用AI生成的
你看他这个里面就帮我分析出来了
我这个用了这个Codex
Harness Engineering的一些
这个实现是吧
然后我的项目结构
有POM
有Admin模块
有Framework
有System
有UI
这个UI是个前段项目
然后它的一个工程规范
就是一些渣滑包
是吧
然后还有一些买白利斯
等等的一些细节是怎么样的
包括我们这个Harness Engineer
它的一个工作流应该是怎么样的
这个就是我之前
落地的一套Harness Engineer
包括它的一些核心的后段命令
这个打包的是吧
编译的
这都是非常核心的一个命令
然后数据库与配置
质量门槛
就是这个就是做一些执行啊
要去确认的一些点
这个是后端的
那前端的话其实也是一样的
前端他特殊的规范的话
就是无非也就是结构啊
是吧
比如技术战是什么
是VU还是React
然后一些啊
包是吧
一些文件奖
他应该放什么组件
他的编码规范啊
是什么
然后JavaScript的
他的编码风格应该是什么样的
包括一些前端命令
MPM的一些命令
包括连条的一些约束
这个就是前端
这个agents.md需要关注一点
所以大家你说怎么写呢
如果你也不知道怎么去写
很简单
你就让AI帮你去生神
让他去分析
大家一定要加这个分析这两个字
就是你不要说
你就直接帮我写一份agents.md
但是你没有提到
让他分析当前项目
但他还是会分析当前项目的
所以你最好写清楚一点
就分析当前项目结构跟代码规范
这样的话
他肯定会把那些目录给他扫一遍
是吧
所以这个就是一个
使用习惯的这个提示词
大家可以做一些优化
所以
agents.md里面大家就可以看到
你看基本上是100行以内
是吧
并且的话写的都是一些关键内容
就是一些非常核心的模块
命令啊
然后配置啊等等的是吧
包括结构
但是非常核心的内容
就大家后段项目
你就可以参考这个去做啊
就这个规范
你可以参考一下
如果是前端的话
你也可以去看一下啊
包括其实我们之前啊
这里写了一个小游戏是吧
这个是我之前写的一个小游戏的这么一个
pacent.md是吧
就是让他分析
我这个里面用python写的啊
你看这个就是python的一套
agent.md的描述是吧
所以怎么来写啊
规范是怎么样的
这里我也给大家说一下技巧
首先啊
大家不知道怎么写
你可以参考一下我这个规范是吧
我这个的话也是用Codex分析
让它写出来
然后大家也可以自己用Codex去分析出来
然后在此基础之上啊
这个是可以改的啊
就比如说AI
它有可能也没有分析出来啊
这个真实的一个情况啊
它有可能是分析错了
所以这个就需要我们
作为开发人员你要去纠正嘛
就是AI他也不能百分百说就没有问题了
所以这里面大家需要自己去看一下啊
就是有问题你就调一下
因为有一些规范的话
AI他分析出来的话
他的描述会有点怪怪的啊
就是没有我们自己作为开发人员那种理解能力啊
就是他可能还不够强啊
当然基本上啊
这个很准啊
大家可以去试一下
看你用什么模型
比如说你用Cloud的模型
或者用Codex 5.3
它的效果很好
但是你用其他模型的话
这个就不敢保证了
所以这个回头大家可以去试一下