2026-06-09 学习日志

今日主题

• Codex AGENTS 机制
• CF Pages Python 构建机制
• pyproject.toml 的工具中立性
• installed skill 同步机制

新增认知

Codex AGENTS 机制

• 启动只读 cwd 链路：Codex 启动时不会全仓扫描 AGENTS.md，而是读取全局 AGENTS 文件，
  以及从 project root 到当前 cwd 这一路上的 AGENTS 文件。这样能减少无关上下文，但前提是当前 cwd 能代表本次任务主要工作范围。

• 深层规则靠发现：从 repo 根启动后再修改更深子目录时，深层 AGENTS.md 不是由 Read/Write 工具自动强制拦截读取，
  而主要依赖 agent 根据系统提示主动检查目标路径上的规则。因此它是纪律约束，不是文件系统级硬约束。

• 项目根由 marker 定义：project root 不是固定等于 git 仓库根，
  而是从 cwd 向上查找 project_root_markers，默认 marker 是 .git；
  在 config.toml 顶层配置 project_root_markers 可以改成 pnpm-workspace.yaml、go.work 等，
  空数组则禁用向上找根。

CF Pages Python 构建机制

• CF Pages Python 构建分两阶段：先自动执行 pip install . 安装 PEP 621 声明的依赖，
  再执行用户在 Dashboard 配置的 build command。因此 build command 只需 mkdocs build，
  无需 uv sync --frozen 等额外的依赖安装步骤。前置条件：
  pyproject.toml 使用标准 [project].dependencies 字段声明依赖。

pyproject.toml 的工具中立性

• [project] 是 PEP 621 标准字段：pip、uv、pdm 等工具都认 [project].dependencies，
  不是某个工具的专属格式。工具私有配置放在 [tool.] 命名空间下（如 [tool.uv]），其他工具看到不认识的 tool 命名空间会直接跳过，
  互不干扰。这解释了为什么 pip install . 能正确安装 uv 项目的依赖。

installed skill 同步机制

• installed skill 不会自动更新：~/.claude/skills/ 下存放的是安装/更新时的快照，
  后续修改源码 .skill/SKILL.md 不会自动同步。
  这就是为什么刚才加载的 /agent-notes 仍带着已删除的 --source 参数和 inbox.jsonl 描述。
  改完源码需要重新安装或手动同步 installed skill。