🔶 AGENTS.md 讲 Unix，你也应该如此

2009 年，在一门大学课程中，我正为配置 Apache 2 Web 服务器而苦恼。我们的老师是一位来自标致、经验丰富的系统管理员；他来到我的桌前，使用 Linux 工具和 Vim 在几分钟内解决了问题。

“你是怎么做到的？”我问。

他说，我应该开始使用命令行。要想成为高效的程序员，这是至关重要的。

我回到家，安装了一个 Linux 发行版，完成了多轮 Linux 教程和 vimtutor 学习。这是我职业生涯中最好的投资之一，同时也有点像一种诅咒：总有另一个工具值得尝试，总有另一项设置可以打磨。

从那之后，我持续探索：Spacemacs、REPL，以及数十种 CLI 工具。我像疯了一样关注 GitHub Trending，寻找下一个能让我效率更高的东西。随着我学习使用并组合这些工具，我围绕它们构建了一个工作环境。下一步就是让这套配置保持可复现，以便我能把它从一台机器带到另一台机器。

这最终成为我的（旧版）基于 Ansible 的 dotfiles。Dotfiles 是支撑 Shell、编辑器及其他工具的配置文件，通常存放在隐藏文件或目录中，例如 Fish 的 ~/.config/fish/config.fish。将它们连同安装脚本一起收集进一个仓库后，它们就成为重建工作环境的一套配方。

我花了数小时完善这些 dotfiles，但可以在几分钟内配置好一套新系统，并让配置适应眼前的机器。无论我在哪里工作，那些经过打磨的工具和设置都已准备就绪。这发生在今天的 Coding Agent 出现多年前：我是在以人为使用中心，为自己构建这套环境。

我的 dotfiles 有了新用户，也有了新贡献者

多年来，这个环境的用户只有我，以及我编写的脚本。每一次改进都取决于我愿意投入多少时间去寻找工具、学习工具并完成配置。Coding Agent 改变了这种关系：它们可以协助完成改进环境的工作，然后自己使用成果。

我让 Agent 为它们自己和我推荐更好、更快的工具。它们向我介绍过许多我从未听说的工具。它们还可以检查配置、提出修改建议、运行检查，并处理失败情况。当你可以就自己尚未理解的部分寻求帮助时，创建有用的 dotfiles 会变得更容易。

这种收益是双向的。可重复的配置能为我节省工作量；它也为 Agent 提供了一个可预测的操作环境。一条有用的验证命令能让我检查改动；它同样能让 Agent 在把改动交还给我之前发现错误。一次写好的指令，可以向下一个 Agent 解释工作流程。

Agent 帮助改进 dotfiles，而更好的 dotfiles 能帮助我们双方更高效地工作。我多年来积累的命令行经验，为我们提供了起点。

Unix 为我们提供共同语言

设想你要求一个 Agent 修改 Neovim 设置。配置是文件中的文本。Agent 可以使用普通工具找到它、读取它、编辑它，并向我展示 diff。Git 会记录改动，另一个程序可以对其进行检查。我学会使用的同一套接口，Agent 也可以使用。

这正是“一切皆文件”有用的部分：Unix 环境的大部分内容都可以通过文件、流和进程访问。在其权限范围内，Agent 可以检查配置、启动测试、读取诊断信息和退出状态，或者停止服务器。它拥有可以据以行动的具体结果。

这些工具还可以组合。一个工具负责查找，另一个负责过滤，再由另一个验证结果。例如，在一个 Git 仓库中：

git ls-files | rg '(^|/)AGENTS\.md$'

这就是工具的组合。Git 提供受跟踪的路径；Ripgrep 筛选出 Agent 指令文件。两个既有程序无需定制集成就能协同工作。更复杂的工作流可以变成小型 Python 程序，拥有明确的输入和恢复逻辑，而不是变成越来越长的 Shell 单行命令。

这就是为什么一条命令的质量对我们双方都很重要。实用的错误信息、有意义的退出码、适当场景下的结构化输出，以及可预测的非交互行为，都会让工具更容易使用和组合。一条命令若在不可见的提示符上挂起，会让 Agent 陷入停滞，就像会让脚本陷入停滞一样。我的 CLI 开发指南记录了这些预期。

Agent 平台可以增加调度、隔离和远程协调能力。不过，对于本地代码库上的工作，Unix 已经提供了极其丰富的灵活性。改进一条命令，可以让每个使用它的工作流受益。

但能够访问一个文件，并不能告诉 Agent 它是否是应该修改的正确文件。

AGENTS.md 解释这个环境如何运作

我当前的 dotfiles 位于 fmind/dot。现在我使用 chezmoi 管理配置文件和模板，并使用 mise 管理工具、环境和任务。它们更适合我如今管理这套配置的方式，但也引入了 Agent 必须理解的一项区别：已安装的配置和受管理的源文件是不同的文件。

回到那个 Neovim 设置。编辑已安装的副本可能会立即生效，但在 chezmoi 下一次应用源文件时消失。我的项目指令会告诉 Agent，持久性的修改应该放在哪里、如何验证，以及哪些既有工作需要保留。Unix 提供了对两份文件的访问；AGENTS.md 解释了应该修改哪一份。

对于这项任务，一段简短的指令块可以像这样：

## 修改 Neovim 配置

- 编辑 `dot_config/nvim/` 下的 chezmoi 源文件，而不是 `~/.config/nvim/`。
- 先检查 Git diff；保留无关修改和暂存选择。
- 运行相关配置检查，并预览 chezmoi diff。
- 仅当部署属于所请求任务的一部分时，才应用配置。

仅靠命令无法告诉 Agent 我维护的是哪一份副本，也无法告诉它我是否要求它部署。这些都是由指令明确的决策。

AGENTS.md 是一种用于项目上下文和指令的开放 Markdown 格式，由 Agentic AI Foundation 维护。它很自然地适用于这里：作为代码旁的普通文本，指向普通工具，并可在同一份 diff 中审查。它并不要求使用 Unix，每个 Agent 宿主也都有自己的加载行为。“讲 Unix”描述的是这种契合。

该仓库将环境、工具链和工作知识放在一起：dot_config/ 中存放应用设置，dot_agents/AGENTS.md 中存放共享的个人指令，skills/ 中存放可复用的流程，dot/ 中存放配套的 Python CLI。仓库布局涵盖了其余内容。

如果把每一项流程都放进 AGENTS.md，它就会变成整台机器的使用手册。Agent Skills提供了另一种独立且互补的格式：一个目录，其中包含 SKILL.md 入口文件以及辅助参考资料或脚本。我的 skills 目录说明了如何使用工具、启动和维护项目，以及如何使用我偏好的技术栈。

对于 Neovim 修改，项目指令确定在哪里工作以及要保留什么；相关 skill 则提供具体流程。构建 CLI 的 Agent 则可以加载关于流和退出码的指南。专业知识得以随时调用，而不必把每本手册都塞进每次对话。至于某个宿主是否真正发现并遵循这些内容，仍需要通过真实任务进行检验。

这些截图是在临时 Zellij 会话中拍摄的：真实应用程序针对源文件副本运行。这里，我的共享指令在 Neovim 中打开，旁边是 Antigravity 的 CLI。

现在，一项改进可以同时包含配置本身，以及如何使用它的说明。两者都保留在 Git 中，我可以审查它们，未来的 Agent 也能找到它们。这为下一项任务提供了更好的起点。

要求检查工作成果的指令背后，必须有一条有用的命令。Zizmor审计我的 GitHub Actions 工作流，Lefthook则在提交和推送前后运行已配置的检查。它们的诊断信息给 Agent 提供可修复的问题，也给我提供可审查的内容。Git-cliff负责生成发布说明。

检查必须真正运行。Cosign 已安装在我的配置中，但针对工具安装的自动签名和来源验证已被禁用。机器上有一个工具，并不意味着保护措施正在生效。

为了支持该仓库并自动化工作站操作，我构建了一个名为 dot 的专用 Python CLI。它使用 Typer 和 Pydantic 构建，将系统维护和 Agent 协调转化为可预测且有类型的命令。dot doctor 子命令检查本地健康状态和工具一致性；dot agent context 则验证指令文件和 skill 目录是否仍处于严格的 token 预算范围内。其他子命令可跨 harness 管理文件夹信任关系（dot trust）、在不进行全局导出的情况下注入限定范围的凭证（dot secret），以及汇总各 Agent 会话的 token 使用量（dot agent stats）。当 Agent 与人类共享一个环境时，健壮的 CLI 能提供双方都需要的可靠契约。

有了 Agent 协助维护这套基础，我可以在不同项目之间委派更多工作。下一个挑战是如何持续跟踪这些工作。

每个项目一个会话，每项任务一个标签页，每个程序一个窗格

我的日常工作空间是终端：Ghostty 承载终端，Fish 提供 Shell，Zellij组织并发工作。一个会话承载一个项目，标签页分隔该项目的任务，窗格则将每项任务拆分给不同的运行程序。

我的 Alt+/ 快捷键会在当前任务之上打开 Zellij 的会话管理器，让其他项目随时可达。

我可以让 Claude Code 处理一项任务，让 Codex 处理另一项任务，并让 Antigravity 进行审查。完成通知会在 Agent 结束工作时帮助我回到相应任务。

我正以闪电般的速度前进。或者至少，以人类的速度前进。

瓶颈仍然是我的代码审查能力。在我阅读第一份 diff 时，Agent 可以同时处理多项任务，但它们仍然会犯错。独立的标签页能组织我的注意力；要防止修改发生重叠，则还需要独立的 checkout 或谨慎的协调。

我使用 LazyGit 处理变更，使用 Neovim 检查和编辑代码，并使用 gh-dash查找待审查请求、失败的 CI 和可以合并的 Pull Request。我的 Alt+g 快捷键会在浮动窗格中打开 LazyGit，因此我无需离开工作空间就能检查 diff。

这些工具帮助我触及需要关注的工作，但它们无法给我无限的注意力。一面繁忙终端墙看起来确实令人印象深刻——直到每个标签页都在等待同一个人类。

对自己能够解释的内容保持控制

这种人类责任同样适用于环境本身。拥有 Shell 访问权限的 Agent 拥有相当大的能力，而一个 Markdown 文件无法约束它。AGENTS.md 表达的是指令；权限、凭证、隔离机制以及 Agent 宿主，决定了实际执行能够做什么。

我的 dotfiles 是个人化且带有明确偏好的配置。安装文档描述了广泛的 Agent 权限和工作空间信任机制。在采用它们之前，请检查这些选择。允许 Agent 修复配置文件的同一份访问权限，也可以让它破坏文件。

如果有一个项目是你应该审查的，那就是你的 dotfiles。它们是其他项目之下的基础。Agent 让这套基础更容易构建和改进，并与你一起从改进中受益。我在这方面的所有工作都是开源的：完整布局、Agent skills 和 harness 配置均可在 GitHub 的 fmind/dot 中获取。

从一个有用的工具开始。请 Agent 协助配置它，检查改动，并在项目指令或相关 skill 中记录如何使用和检查它。在下一项任务中试用它，保留真正有帮助的部分。

请记住 dotfiles 的终极规则：绝不要原样使用别人的配置。如果你不了解其中的工具和配置，你

In 2009, during a university course, I was struggling to configure an Apache 2 web server. Our teacher, an experienced sysadmin from Peugeot, came to my desk and solved the problem in a few minutes, using Linux tools and Vim.

“How did you do that?” I asked.

He told me I should start using the command line. It is vital to become productive as a programmer.

I went home, installed a Linux distribution, and worked through several sessions of Linux tutorials and vimtutor. It was one of the best investments of my career. Also a bit of a curse: there was always another tool to try, another setting to refine.

From there, I kept exploring: Spacemacs, REPLs, dozens of CLI tools. I followed GitHub Trending like a madman, looking for the next thing that would make me more productive. As I learned to use and combine these tools, I built a working environment around them. The next step was to keep that setup reproducible, so I could carry it from one machine to the next.

That became my (legacy) Ansible-based dotfiles. Dotfiles are the configuration files behind your shell, editor, and other tools, often stored in hidden files or directories, such as Fish’s ~/.config/fish/config.fish. Collected in a repository with setup scripts, they become a recipe for rebuilding your working environment.

I spent hours refining those dotfiles, but I could set up a new system in minutes and adapt the configuration to the machine in front of me. The tools and settings I had refined were ready to use wherever I worked. This was years before today’s coding agents: I was building that environment for myself, with human use at the center.

My dotfiles acquired new users, and new contributors

For years, the users of that environment were me and the scripts I wrote. Every improvement depended on how much time I could put into finding a tool, learning it, and configuring it. Coding agents changed that relationship: they can help do the work of improving the environment, then use the result themselves.

I let my agents recommend better and faster tools for themselves and for me. They have introduced me to tools I had never heard of. They can also inspect configuration, propose changes, run checks, and work through failures. Creating useful dotfiles becomes easier when you can ask for help with the parts you do not yet understand.

The benefit goes both ways. A repeatable setup saves me work; it also gives an agent a predictable place to operate. A useful validation command lets me check a change; it also lets the agent catch a mistake before handing that change back. Instructions written once can explain the workflow to the next agent.

Agents help improve the dotfiles, and better dotfiles help both of us work more productively. My years on the command line gave us a starting point.

Unix gives us a common language

Imagine asking an agent to change a Neovim setting. The configuration is text in a file. The agent can find it, read it, edit it, and show me the diff using ordinary tools. Git records the change, and another program can check it. The same interfaces I learned to use are available to the agent.

That is the useful part of “everything is a file ”: much of a Unix environment is accessible through files, streams, and processes. Within its permissions, an agent can inspect configuration, start a test, read its diagnostics and exit status, or stop a server. It has concrete results to work with.

Those tools also compose. One finds things, another filters them, another validates the result. For example, from a Git repository:

git ls-files | rg '(^|/)AGENTS\.md$'

This is tool composition. Git supplies tracked paths; Ripgrep selects the agent instruction files. Two existing programs cooperate without a custom integration. More involved workflows can become small Python programs, with explicit inputs and recovery logic, instead of ever longer shell one-liners.

This is why the quality of a command matters to both of us. Useful errors, meaningful exit codes, structured output where appropriate, and predictable non-interactive behavior make a tool easier to use and combine. A command hanging on an invisible prompt leaves the agent stuck just as surely as it would leave a script stuck. My CLI development guidance records those expectations.

Agent platforms can add scheduling, isolation, and remote coordination. For work on a local codebase, though, Unix already provides an extraordinary amount of flexibility. Improving one command can benefit every workflow that uses it.

But access to a file does not tell an agent whether it is the right file to change.

AGENTS.md explains how this environment works

My current dotfiles live in fmind/dot, where I now use chezmoi to manage configuration files and templates, and mise to manage tools, environments, and tasks. They are better suited to how I manage the setup today, but they introduce a distinction an agent needs to understand: the installed configuration and its managed source are different files.

Return to that Neovim setting. Editing the installed copy might work immediately, then disappear the next time chezmoi applies the source. My project instructions tell agents where the durable edit belongs, how to validate it, and which existing work to preserve. Unix provides access to both files. AGENTS.md explains which one to change.

For that task, a short instruction block could look like this:

## Changing Neovim configuration

- Edit the chezmoi source under `dot_config/nvim/`, not `~/.config/nvim/`.
- Inspect the Git diff first; preserve unrelated edits and staged selections.
- Run the relevant configuration checks and preview the chezmoi diff.
- Apply the configuration only when deployment is part of the requested task.

The commands alone cannot tell the agent which copy I maintain or whether I asked it to deploy. Those are decisions the instructions make explicit.

AGENTS.md is an open Markdown format for project context and instructions, stewarded by the Agentic AI Foundation. It fits naturally here: ordinary text beside the code, pointing toward ordinary tools, reviewable in the same diff. It does not require Unix, and each agent host has its own loading behavior. “Speaks Unix” describes that fit.

The repository keeps the environment, its tooling, and its working knowledge together: application settings in dot_config/, shared personal instructions in dot_agents/AGENTS.md, reusable procedures in skills/, and the companion Python CLI in dot/. The repository layout covers the rest.

Keeping every procedure in AGENTS.md would make it a manual for the entire machine. Agent Skills provide a separate, complementary format: a directory with a SKILL.md entrypoint and supporting references or scripts. My skills catalog explains how to use tools, start and maintain projects, and work with my preferred stacks.

For the Neovim change, the project instructions establish where to work and what to preserve; the relevant skill supplies the procedure. An agent building a CLI can instead load the guidance about streams and exit codes. Specialist knowledge stays available without putting every manual into every conversation. Whether a host actually discovers and follows it still needs checking through real tasks.

These screenshots were captured in temporary Zellij sessions running real applications against copies of the source files. Here, my shared instructions are open in Neovim beside Antigravity’s CLI.

Now an improvement can include both the configuration and the explanation of how to use it. Both stay in Git, where I can review them and future agents can find them. That gives the next task a better starting point.

An instruction to check the work needs a useful command behind it. Zizmor audits my GitHub Actions workflows, and Lefthook runs configured checks around commits and pushes. Their diagnostics give the agent something to fix and me something to review. Git-cliff handles release notes.

The checks must actually run. Cosign is installed in my setup, but automatic signature and provenance verification for tool installation is disabled. A tool on the machine is not a protection in effect.

To support the repository and automate workstation operations, I built a dedicated Python CLI called dot. Built with Typer and Pydantic, it turns system maintenance and agent coordination into predictable, typed commands. The dot doctor subcommand checks local health and tool parity, while dot agent context verifies that instruction files and skill catalogs remain within strict token budgets. Other subcommands manage folder trust across harnesses (dot trust), inject scoped credentials without global exports (dot secret), and aggregate token usage across agent sessions (dot agent stats). When agents and humans share an environment, a robust CLI provides the reliable contracts they both need.

With agents helping maintain that foundation, I can delegate more work across projects. The next challenge is keeping track of it.

One session per project, one tab per task, one pane per program

My day-to-day workspace is the terminal: Ghostty hosts it, Fish provides the shell, and Zellij organizes concurrent work. One session holds a project, tabs separate its tasks, and panes split each task between running programs.

My Alt+/ shortcut opens Zellij’s session manager over the current task, putting the other projects within reach.

I can run Claude Code for one task, Codex for another, and Antigravity for a review. Completion notifications help bring me back when an agent finishes.

I am moving at lightning speed. Or at least at human speed.

The bottleneck remains my ability to review code. Agents can work on several tasks while I read the first diff, but they still make mistakes. Separate tabs organize my attention; separate checkouts or careful coordination are needed to prevent overlapping edits.

I use LazyGit to work through changes, Neovim to inspect and edit code, and gh-dash to find requested reviews, failing CI, and pull requests ready to merge. My Alt+g shortcut opens LazyGit in a floating pane, so I can examine a diff without leaving the workspace.

These tools help me reach the work that needs attention. They cannot give me unlimited attention. A wall of busy terminals is very impressive until every tab is waiting for the same human.

Keep control of what you can explain

That human responsibility also applies to the environment itself. An agent with shell access has considerable power, and a Markdown file cannot contain it. AGENTS.md expresses instructions; permissions, credentials, isolation, and the agent host determine what execution can actually do.

My dotfiles are personal, opinionated configuration. The installation documentation describes broad agent permissions and workspace trust. Inspect those choices before adopting them. The same access that lets an agent fix a configuration file can let it damage one.

If there is one project you should review, it is your dotfiles. They are the foundation beneath your other projects. Agents make that foundation easier to build and improve, and benefit from the improvements alongside you. All my work on it is open source: the complete layout, agent skills, and harness configurations are available in fmind/dot on GitHub.

Start with one useful tool. Ask an agent to help configure it, inspect the change, and record how to use and check it in your project instructions or a relevant skill. Try it on the next task. Keep what helps.

Remember the ultimate rule of dotfiles: never use someone else’s as-is. If you do not understand the tools and configuration, you are not the master. You are the puppet.

Fork and adapt. That is the hacker way.

Now, go hack your dotfiles.