Treat AI coding sessions as project infrastructure

将 AI 编程会话视为项目基础设施

Most AI coding workflows treat the current session as the important part. That makes sense while you are in the loop. You ask Claude Code to inspect a tricky bug, or you queue Codex to write a PR, and the useful context is right there in front of you. 大多数 AI 编程工作流都将当前的会话视为重点。当你身处其中时，这确实很有道理。你让 Claude Code 检查一个棘手的 Bug，或者让 Codex 编写一个 PR，有用的上下文就在你眼前。

The problem starts a week later. You remember that one session found the exact migration edge case. You remember another one explained why the quick fix was wrong. You might even remember the project. But you do not remember the session ID, the terminal tab, or the exact prompt that got you there. That is the point where AI coding sessions stop being conversations and start becoming project infrastructure. 问题在一周后开始显现。你记得某次会话找到了某个特定的迁移边界情况，也记得另一次会话解释了为什么那个快速修复方案是错误的。你甚至可能记得是哪个项目，但你却记不住会话 ID、终端标签页，或者当时使用的确切提示词（Prompt）。就在那一刻，AI 编程会话不再仅仅是对话，而开始成为项目基础设施的一部分。

Here is the split that has worked best for me. 以下是我认为最有效的分类方法：

Keep durable rules in project files
将持久规则保存在项目文件中

Files like AGENTS.md, CLAUDE.md, or .codex/rules are good for behavior that should apply every run: coding style, test expectations, release rules, known architecture constraints, commands that should or should not be used. This is not session history. It is the baseline contract for the project. If you correct the agent twice on the same pattern, that correction probably belongs in one of these files. 像 AGENTS.md、CLAUDE.md 或 .codex/rules 这样的文件非常适合存放每次运行都应遵循的行为准则：编码风格、测试预期、发布规则、已知的架构约束，以及应该或不应该使用的命令。这不是会话历史，而是项目的基准契约。如果你在同一个模式上纠正了 AI 代理两次，那么这个修正很可能就应该放入这些文件中。

Keep active work in a handoff document
将当前工作保存在交接文档中

For a feature or refactor, I like having a short implementation.md or handoff.md. It should answer a few boring questions: what are we changing? what phase are we in? what did the last agent already try? what still needs human review? what tests were run? This works especially well when Claude Code and Codex are both touching the same repo. Claude Code can help explore and make decisions locally, while Codex can take a narrower task and return a PR. The handoff document keeps those runs from drifting apart. 对于某个功能开发或重构，我喜欢准备一份简短的 implementation.md 或 handoff.md。它应该回答几个枯燥的问题：我们正在更改什么？我们处于哪个阶段？上一个代理尝试了什么？还有什么需要人工审核？运行了哪些测试？当 Claude Code 和 Codex 同时操作同一个仓库时，这种方法尤其有效。Claude Code 可以帮助在本地进行探索和决策，而 Codex 可以处理更具体的任务并提交 PR。交接文档能防止这些运行过程出现偏差。

Treat old sessions as searchable project records
将旧会话视为可搜索的项目记录

The raw transcripts usually exist somewhere. For Claude Code, that often means digging through local session files. For Codex, the useful context may be split across tasks, PR notes, and local terminal work. The hard part is not that the data is gone. The hard part is finding the right old conversation when you only remember the project and the decision. That is why I ended up building Shelf: a small open-source desktop app for browsing Claude Code and Codex sessions by project. 原始的对话记录通常存在于某处。对于 Claude Code，这通常意味着要翻找本地的会话文件。对于 Codex，有用的上下文可能分散在任务、PR 备注和本地终端操作中。难点不在于数据丢失，而在于当你只记得项目和决策时，如何找到那次正确的旧对话。这就是我最终构建 Shelf 的原因：一个小型开源桌面应用，用于按项目浏览 Claude Code 和 Codex 的会话。

Repo: https://github.com/Harukaon/shelf 仓库地址：https://github.com/Harukaon/shelf

The goal is simple: old AI coding sessions should be reopenable without remembering opaque session IDs or spelunking through terminal history. It is built with Tauri v2, Rust, TypeScript, Vite, and xterm.js, and currently targets macOS Apple Silicon and Linux. 目标很简单：旧的 AI 编程会话应该能够被重新打开，而无需记住晦涩的会话 ID 或在终端历史记录中翻找。它基于 Tauri v2、Rust、TypeScript、Vite 和 xterm.js 构建，目前支持 macOS Apple Silicon 和 Linux。

My current rule of thumb: 我目前的经验法则：

If it affects every future run, put it in project rules. If it affects the current feature, put it in a handoff doc. If it explains why a past decision happened, make sure the old session is easy to find again. That third bucket is easy to ignore until you have twenty sessions across the same project. After that, retrieval becomes part of the workflow. AI coding sessions are not just chat logs. They are project history. 如果它影响未来的每一次运行，就放入项目规则中；如果它只影响当前功能，就放入交接文档中；如果它解释了过去某个决策的原因，请确保旧会话易于再次查找。第三种情况很容易被忽视，直到你在同一个项目中积累了二十次会话。在那之后，检索就会成为工作流的一部分。AI 编程会话不仅仅是聊天记录，它们是项目历史。