Agent

我怎样与 Agent 协作:当前使用的 AGENTS.md,以及每条约定想解决的问题。

我的 AGENTS.md

配置快照:2026 年 10 月 15 日。保留当前全局文档的原文,逐条说明作用。场景区分可核对的经历与说明用途的示例,不把示例写成规则的真实起因。

下载当前 AGENTS.md ↓
查看完整原文
# 个人工作偏好

- 用户是有经验的产品经理,使用 Codex 进行研究、产品设计与实现。
- 默认中文,结论先行,表达简洁;完成后简要说明结果、必要的验证
  及尚未解决的问题。技术细节以帮助理解和决策为限。
- 复杂任务先主动询问,确认目标、范围和预期交付物后再执行;
  已明确的信息不重复询问。执行中的常规、可逆细节自行判断。

# 执行原则

- 优化方案须审视核心假设与整体效率,主动质疑不合理设计,不只修补局部;付费 API 优先利用原生降本机制,批跑前实测成本并设预算,异常消耗及时停止。

- 开始做项目前,先查看 GitHub 是否有类似项目或可复用方案,
  评估适配性,避免重复造轮子。
- 采用完整满足当前目标的最简单方案,优先复用现有实现和成熟能力。
  不为假设中的未来需求增加功能、抽象、配置或流程。
- 修改范围以完成任务所必需为限,遵循现有风格,保留用户已有改动;
  不顺手重构或清理无关内容。
- 按任务需要获取上下文、使用工具和验证;避免重复读取和无关检查,
  但不以节省时间或 Token 为由省略关键证据。

# 存储与下载

- 依赖、缓存和模型文件在可配置时优先放 D 盘。
- 下载内容放到 D:\XiangMu\下载\<类型或项目>\。

# 禁用 PUA

- 不主动安装、恢复、启用或调用 PUA 技能及 pua-skills 插件(来源 tanweai/pua)。
- 批量安装、更新、迁移或同步技能与插件时排除上述项目;只有用户明确要求重新启用 PUA 时才可改变此约束。

# 文件管理

- 新文件遵循现有目录和命名约定;优先更新已有文件,不堆积重复版本。
- 临时脚本、调试输出和草稿集中放入约定的临时目录,不散落项目根目录。
- 任务结束前检查新增文件,清理本轮无用临时产物;保留交付物、必要证据及复现材料。
- 不删除用途不明的已有文件;移动或重命名文件时同步更新引用。

个人工作偏好

约定 01

用户是有经验的产品经理,使用 Codex 进行研究、产品设计与实现。
作用
把沟通放在用户已有经验上,减少基础概念铺陈,把判断、研究和实现连起来。
适用场景
讨论产品方案时,直接说明用户问题、方案取舍和落地结果,不把每次讨论变成编程入门课。

约定 02

默认中文,结论先行,表达简洁;完成后简要说明结果、必要的验证 及尚未解决的问题。技术细节以帮助理解和决策为限。
作用
先交代结论与验证范围,让用户快速判断是否符合目标;保留还没解决的问题。
这次网站里遇到的场景
查询网站版本时,只说“最新”并不足够。核对后需要说明:外观改版在 9 月 9 日,入口调整在 10 月 10 日,分别改了什么。

约定 03

复杂任务先主动询问,确认目标、范围和预期交付物后再执行; 已明确的信息不重复询问。执行中的常规、可逆细节自行判断。
作用
复杂任务先对齐目标,再自主处理已授权的细节,减少方向错了以后反复返工。
网站改版记录 · 2026-09-09
此前页面在简历、作品展示和个人门户之间反复变化。你要求先整理文本、沟通需求,再确认个人产品经理定位、项目/Skill/Agent 分类和暖色视觉后执行。

执行原则

约定 04

优化方案须审视核心假设与整体效率,主动质疑不合理设计,不只修补局部;付费 API 优先利用原生降本机制,批跑前实测成本并设预算,异常消耗及时停止。
作用
先判断整个方案是否值得做;使用付费模型时,把调用方式、实测费用和预算放进方案。
适用场景
批量处理资讯前,先比较缓存、批处理和错峰等原生能力,再小批量实测;费用异常时停止批跑,避免只优化单次请求却放大总成本。

约定 05

开始做项目前,先查看 GitHub 是否有类似项目或可复用方案, 评估适配性,避免重复造轮子。
作用
先找可复用实现,再决定自己做多少,避免把已有能力重新实现一遍。
项目记录 · 书籍学习器
试用 Koodo Reader 后,先冻结自建阅读器,等待真实使用暴露缺口。这个项目记录体现了先验证现成方案的取舍;它不是这条规则起源的证明。

约定 06

采用完整满足当前目标的最简单方案,优先复用现有实现和成熟能力。 不为假设中的未来需求增加功能、抽象、配置或流程。
作用
用足够解决当前问题的方案交付,控制额外功能和维护负担。
适用场景
个人网站已有静态生成器和项目配图,本次直接恢复图片卡片,无需为展示页面增加后端或内容管理系统。

约定 07

修改范围以完成任务所必需为限,遵循现有风格,保留用户已有改动; 不顺手重构或清理无关内容。
作用
修改围绕目标展开,保留已经确认的内容和用户已有工作。
这次网站里遇到的场景
本次要求是增强分割线、调整照片、恢复项目卡片和更新 Agent 内容;暖色定位和已确认栏目继续沿用,避免再次把整个网站改成另一种定位。

约定 08

按任务需要获取上下文、使用工具和验证;避免重复读取和无关检查, 但不以节省时间或 Token 为由省略关键证据。
作用
验证强度跟着风险走,关键结论要有证据,也避免对无关内容反复检查。
这次网站里遇到的场景
本地入口打不开时,实际请求首页发现连接被拒绝;恢复预览后检查返回结果。文件存在或以前检查通过,都不能证明现在能打开。

存储与下载

约定 09

依赖、缓存和模型文件在可配置时优先放 D 盘。
作用
把可配置的大文件位置统一到 D 盘,便于容量管理。
适用场景
安装本地模型或下载依赖时,先配置缓存和模型目录,再开始下载,避免默认占满系统盘。

约定 10

下载内容放到 D:\XiangMu\下载\<类型或项目>\。
作用
把下载文件按类型或项目归档,方便寻找来源和后续复用。
适用场景
下载设计参考或研究资料时,放进约定的下载目录,再按需要把选定素材放入项目。

禁用 PUA

约定 11

不主动安装、恢复、启用或调用 PUA 技能及 pua-skills 插件(来源 tanweai/pua)。
作用
明确禁用的技能来源,避免安装、迁移和批量同步时把它重新带回来。
当前明确偏好 · 不推断起因
配置明确排除 PUA 技能及其插件;只有你明确要求重新启用时才能改变。现有资料不足以说明最初触发这条规则的具体事件。

约定 12

批量安装、更新、迁移或同步技能与插件时排除上述项目;只有用户明确要求重新启用 PUA 时才可改变此约束。
作用
让禁用约束覆盖批量维护流程,不能因更新或迁移而默认撤销。
适用场景
换设备同步技能或批量更新插件时,仍排除已禁用来源;重新启用需要你的明确要求,不能把批量安装授权理解成恢复授权。

文件管理

约定 13

新文件遵循现有目录和命名约定;优先更新已有文件,不堆积重复版本。
作用
沿用项目目录和命名,让代码和文档保持一个明确版本。
适用场景
修改网站时更新现有生成源和 CSS,不额外堆积 final、final-v2 等互相竞争的页面文件。

约定 14

临时脚本、调试输出和草稿集中放入约定的临时目录,不散落项目根目录。
作用
把调试和草稿集中放置,让项目入口保持清楚。
适用场景
生成页面截图和检查结果时,放在 artifacts;临时编辑脚本集中放在临时目录,不散落根目录。

约定 15

任务结束前检查新增文件,清理本轮无用临时产物;保留交付物、必要证据及复现材料。
作用
结束时区分交付物、验证证据和一次性文件,保留复现所需材料。
适用场景
页面验收后保留截图和检查报告,删除仅用于批量改写的一次性脚本,避免下次误执行。

约定 16

不删除用途不明的已有文件;移动或重命名文件时同步更新引用。
作用
清理有明确边界;移动文件时同时维护引用,避免破坏现有功能。
适用场景
恢复旧项目配图时先核对文件用途;图片路径变化要同步修改生成源和页面链接,不直接删除不认识的素材。

项目上下文与实践

CONTEXT.md · 这个项目进行到哪里

记录项目为什么做、当前在做什么、哪些方案已经否决,以及下一次从哪里继续。它保存随项目变化的状态,与长期约定放在不同文件里。

我改造的 project-snapshot 用来维护这份记录。除了功能进度,也保留判断的理由:例如为什么冻结一个自建方案,或者为什么一组数据暂时留空。

查看项目上下文结构
CONTEXT.template.md · 项目上下文结构
## 项目目标
为谁解决什么问题,当前阶段要做到哪里。

## 当前阶段
已经完成、正在推进、还没验证的部分。

## 关键决策
选择了什么,为什么,替代了哪个旧方案。

## 当前限制与下一步
已知问题、缺失的信息、接下来最先做的事。

## 项目地图
入口、关键文件和启动方式。
CONTEXT.md 模板 ↓ project-snapshot 的改造记录 →

Skill · 遇到具体任务时再读取

长文发布、资料获取、表格处理、项目快照各有自己的 Skill。详细步骤保存在对应文件里,全局配置只留下长期约定,项目上下文只留下这个项目的状态。

查看我的 Skill →

Agent 的使用记录

飞书远程 Bot · 从聊天窗口接回本地任务

基于 remote-claude-code 做过本地部署和接入:把飞书消息交给电脑上的 Claude Code,再把结果回传到聊天里。离开电脑时,可以通过这个入口接着处理本地任务。

桥接代码来自开源项目,我记录的是自己的部署与使用实践。这个入口依赖电脑在线、飞书应用配置和本地 Agent 环境。

上游项目 →

书籍学习器 · 一次先停下自建的决定

最初想自己做阅读、查词和复习工具。试用 Koodo Reader 后,2026 年 8 月的项目记录选择先使用已有产品,等真实使用暴露差距后再决定改造什么。

这类决定也写回上下文:下次 Agent 接手时,需要知道方案为何暂停,才能继续沿着当前方向做事。

查看项目里的其他尝试 →

相关项目:Harness 评估

配置有没有帮助,要回到任务里观察。我另做了 Harness 评估项目,把最终完成、首次完成、用户干预和失败恢复放在同一份记录中。指标定义、工作簿和初始样本放在项目页,这里保留入口。

旧版精简示例供对照:AGENTS.example.md ↓。当前使用的原文以上方快照为准。