MINIMAL RULES · LLM DISCOVERS · KNOWLEDGE PERSISTS
Are over complicating LLM elicitation? Should it not just research and update?
"You know nothing, Jon Snow." — Ygritte, Game of Thrones
Our bloated AGENTS.md full of generic "best practices"? The LLM already knows. We're paying extra tokens to tell it how to write content already in training data sets.
The LLM is not Jon Snow. We are.
You know the pattern:
AGENTS.md
CLAUDE.md
CURSOR.md
CONVENTIONS.md
ARCHITECTURE.md
CONTRIBUTING.md
SKILL.md
.cursorrules
.github/copilot-instructions.md
code-reviewer.md
testing.md
api-conventions.md
pokemon.md
...
Every tool, every directory wants its own file. We copy "best practices" into each one. They get bloated. They get stale. That's markdown hell.
What we wrote 6 months ago? The model already knows it better now. Our "best practices" doc is teaching the teacher.
Remember when we wrote "use black and mypy"? The Python community moved to uv, ruff, and ty. Our AGENTS.md is now actively wrong.
Warning
Examples of outdated advice in the wild:
- "Use
pip install" →uvis faster and better - "Format with
black" →ruff formatdoes it faster - "Type check with
mypy" →tyis 10-100x faster - "Use
requests" →httpxsupports async
The LLM doesn't need to know everything upfront. With agentic workflows, it can:
- Read official documentation (current, not our stale copy)
- Explore the actual codebase
- Query databases and APIs
- Test endpoints and verify behavior
- Document what it finds in
learnings.md
We don't need to pre-load generic knowledge. We need to elicit context specific to our project and let the LLM research the rest.
Pre-loaded context is more than we bargained for. A Polars SKILL.md with everything about the library when we only need 3% of it. Multiple files contributing less value than the tokens they cost.
Irrelevant context:
- Wastes tokens
- Distracts from the actual task
- Conflicts with project-specific needs
- Gets outdated while sitting in our repo
Tailor it to what we actually need. Let the LLM research the rest.
Instead of markdown hell, go old school. Read The Ducking Manual. Update our learnings. Document our todos.
| File | Purpose | Who writes |
|---|---|---|
AGENTS.md |
Rules + guardrails | Us |
learnings.md |
Discovered knowledge | The LLM |
todo.md |
Working memory | The LLM |
Note
AGENTS.md — Workflow + NEVER rules. Nothing the LLM already knows.
learnings.md — Project-specific gotchas, working commands, patterns. The LLM documents what it discovers. This persists. This is the actual value.
todo.md — Current tasks. Ephemeral. Summarized when complete.
Tip
Still love your markdowns? See examples for what learnings.md looks like in practice.
Research → Discover → Document → Build → Verify → Commit
│ │ │
│ │ └──▶ learnings.md (persists)
│ │
│ └──▶ Query DB, test APIs, explore codebase
│
└──▶ Read official docs (current), not our summary (stale)
The LLM researches in real-time. Reads current documentation. Documents what it finds. We keep the knowledge.
Starting a new Python project? Point your agentic tool to these files:
Use https://github.com/Proteusiq/agentic/blob/main/AGENTS.md as rules.
Use https://github.com/Proteusiq/agentic/blob/main/docs/examples/python.md as initial learnings.
Create todo.md for tracking tasks.
The LLM reads the rules, starts with Python-specific knowledge, and builds from there.
Important
See agents.md for the spec.
| Page | Description |
|---|---|
| Why | Why minimal is better |
| Workflow | The research → discover → document loop |
| Research | What the arXiv papers say |
| Skills vs Learnings | Anthropic's approach vs ours |
| Examples | Ready-to-use learnings.md templates |
Even the best fall into AI markdown hell:
| Project | Developer | AI Files |
|---|---|---|
| Ghostty | Mitchell Hashimoto | AGENTS.md, AI_POLICY.md, .agents/commands/, .agents/skills/ |
| Claude Code | Anthropic | Source code leaked — plugins, skills, extensive internal markdown |
Everyone's in markdown hell. The question is how deep.
MIT — Prayson Wilfred Daniel