Working with agents
Reading the Markdown that coding agents write
Ask a coding agent to plan a feature, review a codebase or summarise a day's work and it will usually answer with a file: PLAN.md, REPORT.md, a checklist, a spec. This guide is for anyone new to that way of working who wants to read those files without pain and edit them without side effects.
Published 2026-10-17. Product details checked against Nice Markdown 1.0.4.
What "agentic development" means here
A coding agent is an AI tool that does not just suggest a line of code but works through a task: reading your project, running commands, editing files and reporting back. Claude Code, OpenAI Codex, GitHub Copilot's agent mode, Cursor and others all work this way. Because the agent is working inside your project folder, it naturally leaves its thinking there too, as Markdown files. Over a few weeks a project collects quite a few of them.
The files you will meet
| File | What it is | Who reads it |
|---|---|---|
AGENTS.md, CLAUDE.md and similar | Standing instructions the agent reads at the start of every session: conventions, rules, what not to touch | The agent, every time. You, when you want to change its behaviour |
README.md | The front page of a project. Agents often update it and are told to keep a "current status" section | People first, agents second |
Plans and specs (PLAN.md, docs/feature-x.md) | What the agent proposes to do, often with phases, open questions and a checklist of your decisions | You, before saying yes |
| Reports and reviews | What the agent found or did: a code review, a test summary, an investigation | You, after the work |
Checklists and backlogs (TODO.md, backlog.md) | Lists with - [ ] and - [x] items that both of you tick off | Both, repeatedly |
| Changelogs and decision logs | A dated record of what changed and why | Whoever needs the history |
Why agents write Markdown
Markdown is plain text, so an agent can write it with the same tools it uses for code, and Git can track every change to it. It has headings, lists, tables and checklists, which is exactly the structure a plan or report needs. And it is readable by both sides: the agent parses it easily, and a person can read it in anything from Notepad to a formatted view. If you are new to the format, start with what a Markdown file is.
Reading them comfortably
Agent-written files tend to be long and structured: a 400-line plan with five levels of headings, tables comparing options, and checklists nested inside checklists. In a terminal or a code editor's source view that is hard to scan. A few things help:
- Use a document view. Headings become headings and tables become tables. Your editor's preview pane, GitHub's file view or a Markdown app such as Nice Markdown all do this.
- Navigate by headings. An outline or table of contents lets you jump to "Open questions" or "Your actions" instead of scrolling. Nice Markdown has an Outline panel for this.
- Search inside the file. Agents are consistent about wording, so searching for "TODO", "decision" or your own name finds what needs you.
- Keep several open. A plan, its report and the backlog are usually read together. Tabs beat reopening files.
Editing without breaking the agent's workflow
The agent will read the file again next time it runs, so the file needs to stay what it was: ordinary Markdown, with your changes and nothing else. Two things to avoid:
- Tools that reformat the whole file. Some editors and note apps rewrite every line on save, changing list markers, wrapping text or padding tables. Nothing is wrong with the result as Markdown, but the file now differs from what the agent wrote on every line, so Git shows a wall of changes and the agent may lose track of what you actually altered. Nice Markdown is built to avoid this: a change made in the Visual view alters only the text you edited, or at most the one paragraph, list or table it sits in, and the rest of the file is kept byte for byte.
- Converting to another format. Pasting into Word and back, or saving as rich text, loses the marks the agent relies on.
The most common edit is the simplest: ticking a checkbox. In source, - [ ] Confirm the launch date becomes - [x] Confirm the launch date. In a document view you click the box. Either way the agent sees a completed task when it next reads the file. Short notes work the same way: add a line under the relevant heading and save.
When the agent changes a file you have open
Agents work while you read. It is normal to have a plan open, go to tick an item, and find the agent has rewritten the section in the meantime. If your tool saves over the top, the agent's changes are gone; if it reloads silently, yours are. Look for a tool that tells you the file changed on disk and lets you compare before saving. Nice Markdown shows your unsaved version beside the version on disk and offers three choices: use the disk version, keep your edits, or save your edits as a separate copy. It does not merge the two for you or send anything to the agent; it just makes sure you choose.
A habit that works
- The agent writes a plan and tells you which section needs your decisions.
- You open the file, jump to that section from the outline, and read it as a document.
- You tick what you approve, add a one-line note where you disagree, and save.
- The agent reads the file again when you next run it and carries on from your answers.
The file is the shared contract. Keeping it plain Markdown is what lets you, the agent, Git and every other tool read the same thing.
Common questions
Does the agent see my edits straight away?
Only when it next reads the file, which usually means your next instruction or session. Nice Markdown does not notify or resume agents; it saves a file like any other editor.
Should I commit these files to Git?
Instruction files such as AGENTS.md and CLAUDE.md, yes: they are part of how the project works. Plans and decision logs are usually worth keeping too. One-off reports and scratch notes are a judgement call; many teams keep them in a docs/ or notes/ folder and prune occasionally.
Are agent-written files safe to open?
They are plain text and cannot run anything by themselves. Treat links inside them as you would links in an email from a stranger, especially if the agent was summarising content from the web.