兩個純文字檔取代作者整套智能體框架

I tried the frameworks first. Graph definitions, node types, state schemas, a plugin system with its own lifecycle. Six months later the thing that actually runs my day is two plain text files and a shell.

That is not a humblebrag about simplicity. It is what survived contact with real tasks, and the reasons are boring.

File one: the task file

Before any run, I write one file. Not a prompt - a task file with a fixed shape:

goal:
done_when:
resources:
must_not_touch:
log:

Five lines at minimum, more when the task needs it. The agent reads this file first, and the runtime refuses to start if done_when is empty. That one refusal has caught more bad tasks than any review process I have had.

The file is also the record. When something goes wrong two days later, the task file from that morning tells me what I actually asked for, which is not always what I remember asking for.

File two: the notes file

One append-only file per project, with short entries:

• what broke and why
• what workaround exists and what it costs
• what not to try again

Every entry has a date. When the agent works in that project it reads this file, so it does not repeat a mistake that is already written down. The file grows slowly and it is the only document I have never had to rewrite.

The subtle part: I write these entries for the agent, but they are more useful to me. Half the value is that writing an entry forces me to say what actually happened, in one paragraph, without excuses.

What the frameworks did better

Honesty first: the frameworks gave me things I now miss.

• Inspection. A graph lets you watch a run as it happens. Plain text gives you a log tail.
• Reuse. Exporting a node is real code reuse. Exporting a text file is copying a file and hoping it stays in sync.
• Guardrails. Typed edges prevent whole categories of mistakes. My task file does not.

I am not claiming plain text is better in general. I am claiming that for a small number of tasks run by one person, the coordination cost of the framework was larger than the value it added, and the two files were the part I used anyway.

What I do instead of a framework

• The shell is the orchestration. A loop, a list of tasks, one agent per task, output to files.
• Parallelism is just multiple processes, not graph nodes.
• State lives in the files and in the repo, so it is inspectable with tools I already know.
• Anything that needs a real interface check is a script, not a node.

The limit is scale. The day I need ten agents coordinating on one problem, this breaks down and I will go looking for a real framework. Until then the two files keep earning their keep.

If you run something like this, I would like to know what your task file looks like. Mine is five lines and still feels too long on some days.