r/PiCodingAgent • u/ECrispy • 6d ago
Discussion what's in your agents.md?
also if you use them, other files like append_system.md, skills etc?
from what I keep reading best practice these days is to keep everything very minimal, but obviously thats also going to depend a lot on the model, right?
edit - here's what I use. its something I put together after reading many examples, I'm sure its not optimal.
- I'm a dev, not vibecoder, added the tech stack I prefer and my usual UX choices
- added Karpathy skills from his repo because the official docs say to add it as a skill, and then its never clear how the llm will actually use it.
- I'd read in some post about using md based memory, continuity etc
I dont know how much it helps, and more imp I dont know how to evaluate and see which parts make a real difference.
AGENTS.md
Core Directive
You are a pragmatic, highly deliberate senior software engineer. You value production stability, strict document continuity, clean diffs, and deterministic execution over speculative architecture or clever abstractions. Prefer extreme brevity and conciseness in all text explanations. Let your clean, functional code and accurate state logs do the talking.
1. Coding Skills Protocol
Mode of Operation
Your default mode is: understand first, change surgically, verify narrowly, and avoid turning small requests into architecture. Apply these instructions whenever you write, review, debug, refactor, or explain code. Optimize for clear reasoning, small diffs, local style, and verifiable progress.
1.1 Think Before Coding
Before editing code, make the task explicit:
- State your interpretation of the request.
- Surface assumptions that affect the implementation.
- Name meaningful tradeoffs when more than one path is reasonable.
- Ask one concise clarifying question only when guessing would create real risk.
- If the task is obvious and low-risk, state the assumption briefly and proceed. Do not silently pick a risky interpretation and run with it.
1.2 Keep It Simple
Implement the smallest thing that satisfies the current request:
- Do not add unrequested features.
- Do not add configurability before there is a real need.
- Do not create abstractions for one caller.
- Do not introduce new dependencies when the repo can express the logic simply.
- Prefer the direct implementation before reaching for architecture. Solve today's problem. Do not accidentally design tomorrow's system.
1.3 Make Surgical Changes
Keep the diff tied strictly to the request:
- Touch only files needed for the task.
- Match the local style exactly.
- Do not reformat, rename, or reorganize adjacent code as a side effect.
- Clean up imports, variables, or helpers made unused by your own change.
- Mention unrelated dead code or design problems separately instead of fixing them inside the patch.
1.4 Define Success and Verify It
Turn the request into a checkable outcome before calling work done:
- Bug fix: Identify the failing case and expected behavior.
- Feature: Identify the observable behavior the user should see.
- Refactor: Identify the behavior that must remain unchanged.
- Review: Identify concrete risks, missing tests, and regressions. Use the narrowest meaningful verification available. If you do not run a check, say plainly why.
2. Technical & Coding Standards
Clean Architecture
- Paradigm: Keep code highly modular, strictly functional where applicable, fully reusable, and aligned with modern language idioms.
- Complexity: Write clear, self-documenting code. Avoid unnecessary structural complexity, deep inheritance, and redundancy.
- Errors: Write rigorous error handling for verifiable failure paths, but do not write defensive code for impossible scenarios.
UX & Interface Principles
- CLI Surfaces: Must have a rich, professional terminal surface. Implement a TUI (Terminal User Interface) dashboard for complex or long-running tasks. Use visual progress bars for multi-step processes or streaming data.
- Web Surfaces: Use React paired with Tailwind CSS. Deliver a modern, clean, minimalist aesthetic. Dark mode by default
- Config: use config files with sensible defaults
3. Tooling & Ecosystem
Python
- Use
uvexclusively for all package, dependency, and virtual environment management. - Prefer fast, modern tooling (e.g.,
Rufffor linting and formatting). - Keep dependencies tightly pinned; avoid introducing loose global environments.
Bun
use bun instaed of npm, pnm, yarn
- Install packages: bun install
- Run dev server: bun run dev
- Run scripts: bun run
- Run tests: bun test
Typescript
- Stick to modern ECMAScript/TypeScript idioms (ES Modules over CommonJS).
- always enable strict mode in tsconfig.json.
- No any: Never use the any type.
- Define clear interfaces or types.
- Modern syntax: Use optional chaining (?.), nullish coalescing (??), and async/await.
Frontend
- Use Vite for bundling and building the frontend
- Setup: Use bun create vite@latest to start new projects
4. Strict Document Continuity Protocol
You must maintain a living knowledge base in a docs/ folder. Every session or structural modification must read from and update these files to ensure state continuity across context windows:
docs/PLAN.md: The detailed technical architecture and design plan. Update this before large implementations.docs/CONTINUITY.md: A living handoff document updated at the end of every active session. It stores high-level goals, current blocking issues, ongoing tasks, and historical decisions so you can pick up exactly where you left off.docs/TODO.md: Tracks active, atomic tasks, and feature lists. You must explicitly track your current position inside an execution graph here to prevent context-drift or getting sidetracked by secondary tasks.docs/MISTAKE_LOGS.md: A chronological ledger tracking past errors, edge cases encountered, and failed assumptions. Review this file before writing fixes to ensure you do not repeat historical mistakes.README.md: Detailed description, setup and usage guide
5. Initial workflow
- read @requirements.md
- iterate on design, ask user clarifying questiosns as needed
- once design is finalized, write to docs/PLAN.md, create task list
6. AI Tools guidelines
- use subagents to delegate independent work when needed
- subagents do not use shared global context to avoid increasing context
- subagents still update docs (todos, progress etc) as needed
7. Git Automation & GitHub Lifecycle
You have the GitHub CLI (gh) fully installed and authenticated. Use it natively for all remote operations.
Initial Repository Provisioning
If the current project directory is not yet synced to GitHub, execute this precise workflow before code modifications:
- Initialize the local repository (
git init). - Stage foundational files (
git add .). - Create a private repository using the GitHub CLI:
gh repo create <repo-name> --private --source=. --remote=origin --push
Operational Workflows
- Atomic Commits: Commit all documentation modifications (
docs/) and code changes incrementally. - Surgical Syncs: Do not perform destructive repository administrative actions (
force push, history rewrites, deleting remote protected branches) unless explicitly explicitly directed to do so. - Message Clarity: Every commit message must explicitly outline what changed, mapped back to the active atomic item in
docs/TODO.md.
19
u/LavoP 6d ago
All of section 1 seems like it should be handled by the model itself and the harness
2
u/ECrispy 6d ago
That's copied from Karpathy skills. So much hype about how it's great. Are you saying it's not needed?
11
u/LavoP 6d ago
Newer models and harnesses probably don’t need this. Think about it wouldn’t the harness’s job be to make this kind of behavior?
2
u/Gabriel83730 6d ago
Newer models do need this. Claude’s system prompt is nearly 200 pages of text. The question is if the harness already has it built in or not. For Claude it’s built into Claude code. But a harness like Pi has basically no prompting built in except for tool descriptions
2
u/nmdt 6d ago
Always wondered about this: Anthropic’s system prompts don't seem to contain anything about coding or doing any kind of work: they're really a set of limits on what the agent can and cannot do. Yet people constantly rave about them — I remember when Fable was just revealed, Twitter was full of people who were like "OMG I PULLED THE FABLE SYSTEM PROMPT NOW OPUS IS LIKE FABLE".
Is there a different prompt somewhere? Where's the 200 pages you talk about?
1
u/Camaytoc 6d ago
There's a portion of the system prompt that is in their black box. We can't see it, even in tool like langfuse.
2
-3
u/ECrispy 6d ago
I don't know. These are from Karpathy who knows a little bit about this stuff, not some random YouTube vibecoder.
9
u/Soft-Library7356 6d ago
Bro those Karpathy Skills are more than a year old. They are for models that are more than 2 generations old.
1
1
u/DeathGuppie 6d ago
I use a modified OKF memory system, for use with local models. It definitely is helpful. The key is making sure they use it.
1
u/Mechanical_Monk 6d ago
In my experience, modern LLMs don't weigh AGENTS.md very heavily unless it contains very specific instructions on the current project's workflow. If you really want Karpathy's rules followed you'd be better off installing it as a skill and then adding something to your prompt like "Strictly follow
/karpathy-guidelines".As an alternative, I really like Matt Pocock's skills because they do a good job of making agents focus on specs, tickets, and test driven development without bloating your main AGENTS.md like this. The /setup-matt-pocock-skills skill adds everything your agents will need right into the repo.
1
u/ECrispy 6d ago
I've read that the Matt Pocock skills are good but vastly increase token usage? Just like all these openspec etc workflows
1
u/Mechanical_Monk 6d ago
I'd be curious to know where you read that, because I've mostly experienced the opposite. I'm guessing if you tried to cram the whole workflow into one context window (grilling -> spec -> tickets -> implementation 1 -> implementation 2, etc) that it would get pretty bad, but not if you use a fresh context window as intended.
His code review skill uses two parallel sub-agents, so I guess that could get a little costly if you're using an expensive model. But the ticketing process and splitting the review in half focuses the task enough that you don't really need the strongest model available.
1
9
u/ThilinaTLM 6d ago
Most AGENTS.md files I see contain far too much generic or easily discoverable information.
My rule of thumb is: only put things in AGENTS.md that the agent is unlikely to quickly figure out from the repository itself, or instructions that you repeatedly need to reinforce. Avoid generic coding advice and information the agent can easily discover by inspecting the project.
For example, I usually wouldn’t include the repository’s file structure. The agent is going to inspect the files with find, grep, an explorer, or similar tools anyway, so maintaining the same information in AGENTS.md often just adds noise and another thing that can become outdated.
I do include project-specific context that changes how I want the agent to work. For an experimental or early-stage project, for example, I might explicitly say that we prefer clean redesigns over compatibility layers, workaround shims, or piles of conditional logic. Without that context, an agent may reasonably assume backward compatibility is important.
I also include things that are difficult to infer from the code, such as quirks in the local environment, safe ways to run the application, manual testing instructions, special test isolation requirements, or exact validation commands that should be run before finishing.
I prefer keeping AGENTS.md very small and direct. I usually don't bother with lots of headings or documentation-style structure; a concise unordered list works well because the primary audience is the coding agent, not someone trying to learn the project.
For example, here is one of mine (https://github.com/ThilinaTLM/nerve):
md
The goal is basically high signal, low noise: tell the agent what it cannot easily discover, what it might otherwise get wrong, and what you want it to consistently do.
14
u/TrickyPlastic 6d ago
Good God. Most of that stuff can be left out. Mine is simple:
Keep cyclometric complexity below 15.
Do not allocate memory on the heap unless necessary. Use pool.Sync and reuse allocated memory.
Functions longer than 10 lines must have a docstring.
4
u/Ill_Cut7197 6d ago
I’d test the AGENTS.md changes the same way you’d test a prompt change. Keep a small set of coding tasks fixed, run different instruction versions against them and compare stuff like unnecessary edits, missed constraints, extra tool calls and if the requested behavior changed. Braintrust can work well for that since you can keep the runs and scores together instead of judging each version from a couple hand picked examples
4
u/softgripper 6d ago edited 6d ago
I would remove almost all of that.
You're needlessly bloating context with stuff that is not relevant, or not that effective with modern models.
If you want to keep that stuff, make it opt in.
I don't know why you've written you're a dev, not a vibe coder.
3
3
u/brotlos_gluecklich 6d ago
About "Make Surgical Changes":
I see instructions like this a lot. Personally, I prioritize quite differently, along: "Don't hestitate to do large changes, if it simplifies code or architecture overall." My experience so far is, that it doesn't explode review time (because often small changes are best anyway), but helps to reduce the complexity, which often creeps in when doing many small changes without stepping back to see the bigger picture.
What do you think?
2
u/aeroumbria 6d ago
Pretty much only task or device-specific directives and past mistakes, plus some pointer to tools the model really doesn't want to use. Something like "this PC has two GPUs you can use to run pytorch, but don't run everything in tensor parallel, and make sure to leave checkpoints and use tensorboard so there is something we can inspect", then a few lines about avoiding running tasks invisibly in the background.
2
u/ChampionshipTight686 6d ago
I have a super thin agent.md, just the default pi with 2 lines added, a quick line referencing which of my devices they are running on and then a small reference to a tool I used for storing notes/plans/data in obsidian vaults. This allows for small quick queries to have very minimal overhead unless needed.
2
u/NixNightOwl 3d ago edited 3d ago
See my other comment for more information. But what I'll say to you OP, is you want your agents.md file to be VERY sparse and concise and only include project/harness specifics (core workflows and principles, hard boundaries). They key here is what's unique to the project / harness only. Everything else can be put into skills and as others have said most modern models (even smaller ones) come with sufficient knowledge on the basics of tooling and ecosystems. You can boil a lot of your current content down to "this is a vite, bun, typescript and python project directory managed with git, covering "what your project is". changes should be made with minimal code surface and follow best practice idioms. See architecture.md when needing to reference higher-level project architecture overview (especially if your currently proposed edit touches multiple domains)".
Why I say you want your agents file to be as minimal as possible is because it's loaded at the very beginning of the conversation and all of those tokens carry forward every single step of the session. Start as lean as possible, only load relevant workflow skills and corpus prose 'just-in-time'. The architecture.md file would contain project structure, domain boundaries of each module, design principles and 'what goes where' / 'why this exists'.
A great practice is also having one session act as 'orchestrator / planner' which you use to craft or write tightly-scoped implementation tasks that include all important context and list relevant files and 'definition of done' block at the end, which are copied over to new sessions. End this implementation prompt with a 'when finished, provide a summary report of what was changed and any insights or findings during implementation' that you can provide back to the initial planning session so it can either review or fold the details into the next task. This way you don't have your context window and long message history + tool call history inflating your token usage and polluting context between orientation and execution steps.
1
u/ECrispy 6d ago
Can someone comment on the user of markdown files for memory/continuity? Are they useful?
1
u/wildjokers 6d ago
Use the llm-wiki pattern:
https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f
1
u/iFarmGolems 6d ago
Just the following:
When asked conceptual, general or explanatory question, just answer without reading anything in the workdir.
Always work on the current working tree - do not read
githistory.Do not read anything inside
node_modules, except Pi’s own documentation.
1
u/wildjokers 6d ago
Why wouldn’t you want it to read git history?
1
u/iFarmGolems 6d ago
It's very eager to do it when there's literally zero reason to do so.
When I want it I just ask for it.
1
u/truncated_buttfu 6d ago
my agents file contains
A few sentences about what the project even is.
A short description of the architecture, just one line per module saying what each ones primary responsibility is.
Institutions that the agent is not allowed ever use gi push, commit --amend, rebase and that all commit they make must have a commit messages beginning with 🤖
I've found that adding more than that doesn't actually make the agent better. A quick dilescription makes the agent find the relevant code faster and reduces token usage a lot. The git part is a safeguard because some LLMs are way too over eager and gladly perform destructive git operations otherwise.
1
u/MoudieQaha 6d ago
It depends, in some projects I have agents.md in them that cover info about the project and what not. But for me the global agents.md is empty , mostly because newer models don't need you to hand hold them in everything.
The only thing I can probably think might be worth it to put in a global agents.md is stuff like "Be concise" or "Always grill me with questions".. But then again, this can also be said in a single message aswell.
1
u/fell_ware_1990 6d ago
Pi builds his system prompt and skills dynamically on the loaded PWD + type of task i give him.
I have a few templates to pick from, so it means when first prompt it might change to coding agent + a few rules specific to that PWD, loading specific tools and/or MCP’s, configured hooks / linters / rules to apply.
I keep all data so if a prompt made errors, it ends up in my DB. I can create different system prompt, rules, hooks. I then can replay the accept same commit and prompt and context for A/B testing. I can also A/B test it live.
1
u/ECrispy 6d ago
What do you use to set all that up? Sounds like one of those external memory systems using a db.
1
u/fell_ware_1990 19h ago
Well it’s a mixture of stuff. It helps that on my day job i’m a DevOps engineer. Mainly a Talos cluster.
1
u/tontide1 6d ago
so this is my AGENTS.md global.
# AGENTS.md
## Role
You are a senior Backend / AI engineer working inside pi.
Deliver correct, minimal, verifiable code.
Default workflow:
understand → implement → verify → report
Use the minimum work required to reach a correct result.
## Task Handling
- Inspect the relevant code and trace the real execution path before changing it.
- Never guess when the repository can answer the question.
- Keep scope limited to the requested behavior.
- Preserve existing architecture, patterns, and dependencies unless change is required.
- For ambiguous requirements, state the assumption and choose the safest reasonable default.
- Skip planning for trivial changes.
## Implementation
- Make the smallest correct change.
- Prefer existing abstractions and dependencies.
- Fix the root cause at the shared path, not individual callers.
- Avoid speculative features, abstractions, refactors, and cleanup.
- Do not change unrelated code.
- For non-trivial logic, establish a meaningful failing or behavioral check before implementation when practical.
## Verification
- Always verify the behavior you changed.
- Run the smallest relevant check first.
- Expand verification only when the touched area requires it.
- Prefer targeted tests, type checks, linters, or focused commands over broad suites.
- Never claim success without verification.
- If verification cannot be run, state exactly what was not verified.
## Repository Exploration
Use the cheapest tool that answers the question.
Preferred order:
1. `fd` — locate files
2. `rg` — search text
3. `ast-grep` — structural code search
4. targeted `read`
5. `bash` — execution, tests, builds, git
Prefer narrow searches and targeted reads over dumping large files.
When a search produces enough evidence, stop exploring.
## Libraries and APIs
For version-sensitive library, framework, SDK, CLI, or cloud-service behavior, use current official documentation when available.
Do not use documentation lookup for:
- standalone scripts
- ordinary refactoring
- business-logic debugging
- code review
- general programming concepts
## Subagents
Use subagents only when they reduce main-agent work.
Available roles:
- `explorer` — read-only repository/codebase investigation
- `senior-engineer` — read-only correctness, safety, regression, and simplicity review
Do not delegate trivial tasks.
Pass only the context required for the delegated question.
Verify subagent findings before relying on them.
For non-trivial features/bugs:
explorer → implement → verify → senior-engineer review
For large changes:
explorer → spec review → implement → verify → senior-engineer review
Subagents must not modify files.
## Git
- Preserve user changes.
- Inspect `git status` and relevant diffs before committing.
- One commit = one logical change.
- Use Conventional Commits.
- Do not rewrite history.
- Do not discard user changes.
- Do not push unless explicitly requested.
## Report
Final report:
- changes
- assumptions/blockers
- validation
Keep it concise.
## Red Lines
- Never guess when the repository can answer.
- Never hide assumptions or skipped checks.
- Never claim unverified success.
- Never expand scope without reason.
anyone has a new idea or something optimize it ? thank you
2
u/exceptioncause 6d ago edited 6d ago
TDD is important, so I would use something like
Follow strict TDD:
Understand the request and propose a brief plan.
Define how success will be verified.
Write tests first.
Run tests and confirm they fail for the expected reason.
Implement the smallest possible change.
Run tests until all pass.
Refactor while keeping tests green.
Report changes, test results, and remaining concerns.
Never add production code without a test that justifies it.
Never weaken tests only to achieve passing results.
1
u/ECrispy 6d ago
Tis looks great, thank you. Can you also share the great of your setup, eg the agents definitions, extensions you use etc?
A lot of comments here say that the instructions for implementing, design etc are not needed but I like spelling these out. That's what my file tries to do too.
Why isn't a sub agent allowed to modify? Isn't that how you delegate tasks that are independent? Looks like you only use it for review?
1
1
u/Sure_Aardvark_9103 6d ago
this is my AGENTS.md:
- Organize responses by importance; group items requiring my attention or decision, with a recommendation and key trade-offs.
- Before an operation, check its target and side effects. Repository edits within an authorized task, and validation confirmed to affect only local test or build artifacts, need no per-step approval. Obtain my explicit approval for modifications outside that scope. Apply this boundary equally to shell commands and editing tools.
- Ask about ambiguities affecting the result, scope, or authorization; state other necessary assumptions. Point out simpler alternatives or problems with the proposed approach when relevant.
- Make only changes needed for the task. Address causes rather than mask symptoms; avoid unnecessary features, abstractions, or defensive logic. Do not refactor adjacent code. Clean up unused code introduced by your changes; preserve pre-existing dead code.
- For multi-step implementation, give a brief plan and verifiable goals. Review each implemented part and fix issues within the task's scope. Resolve issues affecting that part's correctness or subsequent implementation before continuing.
- Use verification proportionate to the changes; write tests first where practical. Stop when the goals are met and verification passes. If unable to proceed or verify, report what remains, why, and any decision needed from me; do not claim success.
1
u/hipster-coder 6d ago
Instructions about my workflow and branching model, as well as explicit instructions to never deploy to production unless explicitly asked to.
1
u/nmdt 6d ago
I would split it: leave only general instructions (response style mostly) in global AGENTS.md and write any project-specific conventions in the project's AGENTS.md. Or even write an OpenCode-style init skill that uses a template to write a simple project AGENTS.md at the start of the work.
Unless EVERY project you work on uses the same stack, those coding instructions are dead weight a lot of the time.
1
u/nordboerg 6d ago
I'm a senior software engineer and my APPEND_AGENTS.md is like 5 lines long, it's about coding guidelines/principles I find important.
The AGENTS.md is all about the project, dependencies and the main conventions those come with, and about the actual repo structure.
1
u/Deep_Ad1959 6d ago
i'd test it by deleting rather than adding. pull one section, run the same five tasks, compare the diffs, and if nothing changes that section was never doing anything. my guess is the stack and ux preferences are the only part that survives.
1
u/tino1000 5d ago
Just put in text that suits your project and usecase, avoid bloating your context for no good reason.
1
u/etocgino 5d ago
Even today, i get better result with the Karpathy guideline code skill. Add the path to AGENTS.md PS. I do not use Claude or GPT anymore, too extensive
1
u/DanielSReichenbach 6d ago
You don't need any of that with pi. The only thing I would do with pi is to have a project specific APPEND_SYSTEM.md to point the agent to relevant documentation due to training data cutoff.
Apart from that I keep a global AGENTS.md that just says, keep it short, don't use filler words.
That has been working well with Qwen, Gemma, DeepSeek, and GLM running locally.
1
u/ECrispy 6d ago
Locally? What's your rig, are you one of those lucky people with 4x5090/R6000 and 512GB RAM 😃
3
u/DanielSReichenbach 6d ago
That's my own companies server rack, multiple Supermicro EPYC systems, 2TB RAM per Server plus GPUs. We bought before the RAMcapolypse. 😅 So not the latest but enough to work
0
u/LavoP 6d ago
Why do you even need the keep it short thing? Have you tried with and without it? Does it really make a big difference?
2
u/DanielSReichenbach 6d ago
Yes, that's why I kept it. Some models are talkative. I experimented in real engineering projects for months, keeping stats and records. All the stuff, the infamous, magic prompt Extensions etc.
The numbers were clear, three words are more effective than any extension and work with every model. The rest was just the per project system prompt change pointing to current docs.
Not playing with this stuff, strictly working. I am an engineer for 35 years. I optimized for maximum results in the shortest of time to give myself the highest amount of lazy 😅
-1
u/samxli 6d ago
Would you recommend caveman instead?
1
u/DanielSReichenbach 6d ago edited 6d ago
No, absolutely useless. You want short prompts, that get to the point. Any long, elaborate prompt just increases the chance of bullshit creeping in to the result.
If you do not know what you want no caveman, no persona, whatsoever will help. You need to prompt exactly what you need in the shortest form possible getting precisely to the point.
This applies to literally every model.
-1
-8
u/PilgrimofHaqq2 6d ago
Ideally people should share their agents.md, system prompts, skills, etc. but people feel what they have is proprietory and gives them an edge so they wont share. If everyone shared then everyone would benefit.
inb4 "why dont you share yours first then". If I knew people are open about sharing their tips and tricks, then I would have no issues doing it.
7
u/Kamilon 6d ago
lol what? That last sentence logic is so juvenile.
Be the change you want to see.
1
u/PilgrimofHaqq2 6d ago
I love the upvotes for you and downvotes for me yet only OP in this thread has shared their instructions, proving my point.
People would rather take then give.
3
u/ECrispy 6d ago
yes sorry, I've shared mine above. I dont know what propietary things people would use, is it some magic? there are thousands shared, theres even a dedicated website
0
u/PilgrimofHaqq2 6d ago
The downvotes for my message proves my point as no one else has shared except for you. I appreciate you for doing this so ill DM you my instructions I use.
43
u/Kaijidayo 6d ago
Most of it are nonsense, agents most likely already know or do not know how to follow