agent-knowledge-framework: Instructions file for Codex

Agent Notes

每个 agent 在开始任何任务前，必须先通读本文件和角色 AGENTS.md，再开始动手。

仓库结构

agent-knowledge-framework/
├── base/                       # 通用知识（所有角色共享）
│   ├── experience/             # 不属于特定角色的经验
│   ├── principles/             # 通用原则和规范
│   ├── skills/                 # 通用技能（每个技能目录主入口为 SKILL.md）
│   └── insights/               # 通用洞察（跨角色的规律性认知）
└── roles/                      # 各角色目录
    ├── cli-tool-dev/          # CLI/TUI 工具开发
    ├── maintainer/            # 知识仓库维护
    └── <role>/
        ├── AGENTS.md          # 角色描述 + 知识索引（始终加载）
        ├── principles/        # 角色专有原则
        ├── skills/            # 角色专有技能
        ├── insights/          # 角色专有洞察
        └── experience/        # 角色经验复盘

知识加载与沉淀

• 常驻 context：AGENTS.md（本文件）+ roles/<role>/AGENTS.md
• 按需加载（分层）：角色/目录 AGENTS.md 索引 → skill/principle/insight → experience（按 source 或 "Escalate to experience if" 升级）
• 症状/高风险直达：出现特定报错或做迁移/发布/权限操作时，可直接用关键词检索 experience
• Context 压缩后：如果你不确定索引内容或协作规则细节，说明 context 已被压缩，立即重新 Read 本文件 + 角色 AGENTS.md

详细的加载策略（常驻 vs 按需判断标准、experience 唤醒、摘要写法）见 base/principles/knowledge-loading.md。

完成重要工作后（PR review 修复、跨层 bug 修复、首次跑通流程、踩坑），agent 应主动沉淀经验。知识分类（experience/skill/principle/insight）、存放位置判断、提炼流程和反模式，见 base/knowledge-sedimentation.md。

多 Agent 协作规则

本仓库假定多个 coding agent 可能同时修改，所有写操作必须遵守以下规则。

Agent 工作中涉及两类仓库，规则同样适用：

• Agent 目录（本仓库）：存放角色知识、经验、技能文档
• 工作目录（实际代码仓库）

1. 所有写操作必须在 worktree 中进行，禁止直接 push main

始终创建 worktree，不要在主工作目录中 git checkout 或 git checkout -b 切分支。只读操作可以在 main 上进行。

常见违规模式（禁止）：

• git checkout -b <branch> 然后直接在主工作目录编辑——这不是 worktree，只是切了分支
• "先写完再搬到 worktree"——一旦开始编辑就很难搬，必须一开始就在 worktree 里

正确流程：

git fetch origin
git worktree add .claude/worktrees/<topic> -b <agent>/<topic> origin/main
cd .claude/worktrees/<topic>
# ... 编辑、commit ...
git push -u origin <agent>/<topic>

关键：永远基于 origin/main 创建 worktree，不要基于本地 main（可能过时）。详见 base/principles/git-worktree.md。

检查点：执行任何 git checkout -b 或文件编辑前，先问自己"我现在在 worktree 里吗？"。如果 pwd 不包含 .claude/worktrees/，停下来，先创建 worktree。