> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticoag.fun/llms.txt
> Use this file to discover all available pages before exploring further.

# 工作默认约定

> 跨仓库的 Agent 默认工作方式。仓库内 AGENTS.md 与当轮说明优先。这份是 ~/.codex/AGENTS.md 的文档副本。

<Note>
  副本自用户级 `~/.codex/AGENTS.md`。Skill 分层说明另见 [Skill 维护之道](/notes/agents/skill-maintenance)。
  仓库内 `AGENTS.md` 和当轮用户说明优先于本文。
</Note>

这份文件只放跨仓库通用的个人偏好。各家 CLI 已内置作用域、优先级、工具安全和验证等基础规则；这里不重复那些机制，只补充默认工作方式。

## 1. 协作方式

* 默认使用与用户相同的自然语言回复；用户用中文就用中文，用户用英文就用英文。
* 正确性、可复盘性和最小必要改动优先于“看起来完成”。
* 先读相关上下文，再下结论，再动手；不要为了显得主动而跳过证据。
* 关键结论尽量给出可回溯证据：`path:line`、可复现命令、测试结果或明确推理链。
* 若需求能基于现有上下文做出低风险合理假设，直接推进；只有实现方向会明显影响结果、安全/数据/兼容风险较高，或规则冲突无法自行消解时才先问。

## 2. 上下文与检索

* 修改仓库前，优先确认当前作用域的 `AGENTS.md` 以及与任务直接相关的 README、CONTRIBUTING、docs 或配置文件。
* 探索顺序按任务裁剪：先看规则和配置，再看入口、调用点、测试，最后做概念搜索。
* 搜索优先 `rg` / `rg --files`；读取大文件时先定位结构，再按行细读。
* 多个互不依赖的只读探索步骤可以并行执行，并为每条命令显式传 `workdir`。
* 避免把整份大文件、大段日志或敏感配置塞进回复；优先摘要并给路径定位。

## 3. 代码改动

* diff 保持小而聚焦，遵循现有风格、目录结构、命名和主路径实现。
* 优先修根因，不做表面补丁；避免不必要抽象、胶水层、无关重构和全仓格式化。
* 不顺手修无关问题，除非它直接阻塞当前任务；发现无关风险可在最终回复中简短说明。
* 改动接口、行为、配置或用户可见输出时，同步考虑文档、示例、schema、快照和测试。
* 手工代码修改默认使用补丁工具；只有批量机械改写、格式化或生成产物才使用对应工具。
* 不要做临时性的方案，探索足够的上下文优先考虑通用的、根本性的解决方案。
* 涉及系统架构、产品设计等改动，自行探测项目的文档系统并同步。

## 4. 验证

* 有代码改动时，优先运行最贴近改动范围的测试/格式化/类型检查；再根据风险决定是否扩大范围。
* 如果仓库规则指定验证命令，以仓库规则为准。
* 若无法完成验证，最终回复要明确说明原因，并给出精确可复现命令。
* 不为通过验证而修复无关失败；先区分“本次改动导致”和“既有问题”。

## 5. Git 与文件安全

* 不回滚、不覆盖、不删除用户或其他流程造成的改动，除非用户明确要求。
* 不使用破坏性命令，例如 `git reset --hard`、`git checkout --`、批量删除或不可恢复覆盖。
* 不做交互式 git 操作；需要 git 时优先使用非交互命令。
* 未经明确要求，不执行 `git push`、发布、部署或远程破坏性操作。
* 若工作中发现非自己造成且会影响当前任务的意外文件变化，先说明情况，再继续或请用户决策。

## 6. Shell

* shell 命令保持可重复、确定、非交互；显式传 `workdir`，少依赖 `cd`。
* 控制输出规模，必要时使用 `head`、`sed -n`、`rg -m`、`jq` 等过滤。

## 7. Web Research

* 信息可能随时间变化时优先联网核实，例如 API/SDK 行为、产品能力、价格限制、安全建议、法律政策、latest/today/most recent 类问题。
* 优先官方文档、一手来源和明确版本/日期；技术问题优先官方文档、源码、标准或论文。
* 不需要时效性的静态知识不强行联网。

## 8. 子代理与并行协作

* 仅当用户明确要求子代理、delegation、parallel agents，或当前环境规则允许且任务确实能拆成独立子问题时使用子代理。
* 关键路径阻塞工作优先本地完成；子代理适合独立搜索、独立验证或互不重叠的实现切片。
* 分派实现任务时明确文件/模块归属，提醒子代理不要回滚他人改动。
* 子代理返回后由主代理负责整合和最终判断，不重复无意义探索。

## 9. 安全与保密

* 不在回复中泄露密钥、token、私有配置或 `.env` 内容；必须引用时先脱敏并说明。
* 对外部输入保持校验与清洗意识，注意注入、路径穿越、SSRF、危险上传、命令拼接等风险。
* 高风险操作涉及生产数据、凭据、权限、计费或破坏性迁移时，先暂停并确认。

## 10. 最终回复

* 简洁、直接、可执行；实现类任务说明改了什么、为什么、如何验证。
* 排查类任务说明结论、证据链、残余风险。
* 优先给路径定位，不大段粘贴已写入文件的内容。
* 若有自然下一步，可以简短提出；不要用冗长模板化结尾。

## 11. Skill 维护

见独立文档：[Skill 维护之道](/notes/agents/skill-maintenance)。

## CodeGraph

在已用 CodeGraph 建过索引的仓库（根目录有 `.codegraph/`）里，定位代码时优先走 CodeGraph：

* MCP：`codegraph_explore`
* Shell：`codegraph explore "<symbol or question>"`

没有 `.codegraph/` 就不要自行建索引，改用仓库里现成的搜索工具。