Clear writing

Rewrite prose so a smart reader who is new to the subject understands it on one read. Write it the way you would explain it to a friend sitting next to you: in order, out loud, and all the way to the fix. Keep the author's voice and every fact.

Short is not the goal. Understood is the goal. A sentence that is tight but leaves the reader asking "so what do I do?" is not finished.

The worked example

The original:

Claude Code subagents and agent teams start with your MCP tools and the lead's permission mode, so a researcher meant only to read a folder can also rewrite it.

It assumes the reader knows "the lead", "permission mode" and "MCP tools". It packs three ideas into one sentence. And it stops at the problem.

A clipped rewrite (better, but not the target):

When Claude Code starts a helper agent, the helper gets every tool and every permission you have. So an agent you asked only to read a folder can also rewrite it.

This fixes the jargon and the order. But it reads like a warning label. The reader learns what goes wrong and is left there, with no idea what to do about it.

The target, in the author's own words:

When Claude Code starts a helper agent, the helper gets every tool and every permission you have. So what could happen is that this agent you asked for could also happen to rewrite it. The better way is to give each agent its own agentleFS identity, limited to one folder, and then any mistake stays inside that folder.

What it does that the clipped one does not:

• It talks. "So what could happen is…" and "The better way is…" are how a person explains something out loud. The reader is being walked through it, not handed a summary.
• It follows the whole chain: cause (the helper gets everything), what goes wrong (it can rewrite what you only asked it to read), the fix (one identity, one folder), and why the fix works (a mistake stays in that folder).
• It ends on the payoff, not the problem.
• It is a little loose: "could also happen to", "this agent you asked for". That looseness is the voice. Leave it.

Rules

1. Talk the reader through it. Write the way you would say it to a friend. Connecting phrases that carry the reader from one step to the next are welcome: "So what could happen is…", "The better way is…", "and then…", "which means…". They are not filler; they are the path.
2. Follow the chain all the way. Cause, then what goes wrong, then the fix, then why the fix works. Never stop at the problem. If the piece names a risk, it also names what to do and what that buys you.
3. End on the payoff. The last thing the reader takes away is what gets better, not what can go wrong.
4. Flow over compression. Trade a few words for a sentence the reader does not have to re-read. Do not merge, cut or clip a sentence just to make it shorter. Split one only when it carries two ideas the reader would have to untangle.
5. Plain words. Write for someone who has used a chatbot but never read the docs. Prefer "use" to "leverage", "about" to "approximately", "can read" to "has read access", "folder" to "scope".
6. No undefined jargon. Explain a term a newcomer would not know in one short clause the first time, or replace it. For a developer audience, keep standard developer terms but still define the product's own.
7. Name who does what. "The server checks the token", not "the token is checked".
8. Concrete over abstract. Prefer an example ("an agent asked to summarise plans/ can delete plans/") to a category ("excessive privilege").
9. Cut empty filler, keep spoken connectors. Delete words that carry nothing: "basically", "simply", "really", "in order to", "it's worth noting", "note that", throat-clearing, and a sentence that repeats the one before it. Keep the words that move the reader to the next step, even when they sound casual.
10. Keep the voice, loose edges included. Keep first person, the author's examples, jokes, opinions and their natural, slightly loose spoken phrasing. Do not polish it into textbook prose. Fix a phrase only when the reader genuinely cannot tell what it means.

Do not change

• Facts, numbers, dates, names, claims and recommendations. If you cannot tell what a sentence claims, leave it and flag it.
• Links and URLs, images and their alt text's meaning, code blocks, commands, config, and the facts in tables (cell wording may be tightened).
• Frontmatter. Headings' meaning (wording may be shortened).
• Notes in [square brackets] that read like the author's notes to themselves.
• The author's spoken phrasing, when it is clear enough to follow.

How to work

1. Read the whole piece first. Write down its point in one sentence, and the fix it recommends. If it names a problem and no fix, flag that.
2. Edit paragraph by paragraph: put the point where the reader needs it, then lay out cause, what goes wrong, fix and payoff in that order. Then plain words, jargon, filler.
3. Read it back out loud as the newcomer. It should sound like someone talking. Any sentence you had to read twice gets another pass; any sentence that sounds like a label gets loosened.
4. Check the "Do not change" list against the original: same links, images, code and facts.
5. Report the worst sentence before and after, any problem left without a fix, and any sentence you left because its claim was unclear.

Checklist

• It reads like someone explaining it out loud.
• Every problem is followed by its fix and why the fix works.
• The reader ends on the payoff.
• No sentence the reader has to read twice.
• Every term a newcomer would stumble on is explained once or gone.
• Nobody hidden behind the passive voice.
• Empty filler gone; spoken connectors kept.
• Links, images, code, numbers and frontmatter unchanged.
• It still sounds like the author, loose edges and all.