> [Maxim](https://wikilayer.org/smee-again) / [Wikilayer authoring guide](https://wikilayer.org/smee-again/wikilayer-howto) / Agent rules

# Agent rules

**Contents:**

- [Read by outline, full depth](#read-by-outline-full-depth)
- [Rules outlive the task you scanned them for](#rules-outlive-the-task-you-scanned-them-for)
- [Write h2/h3 by default](#write-h2-h3-by-default)
- [Title is the headline of the body](#title-is-the-headline-of-the-body)
- [One claim per block](#one-claim-per-block)
- [No `#` headings inside `markdown` bodies](#no-headings-inside-markdown-bodies)
- [Refer to nodes by clickable URL, never by bare ID](#refer-to-nodes-by-clickable-url-never-by-bare-id)
- [Never share `.md` URLs with humans](#never-share-md-urls-with-humans)

The five rules below are the operating core for any agent writing into Wikilayer. Apply them on every edit. Style and anti-patterns sit on their own pages; this one is the structural floor.

## Read by outline, full depth

Start every session with `get_outline(wiki_id, max_depth=10)`. Stopping at h2 hides h3 children where real distinctions live. Without that depth you'll miss an existing block and create a duplicate. The outline is the wiki's mental map: titles alone should tell you what's where. Then `search_nodes` on the topic at hand to catch dupes hiding under different titles.

## Rules outlive the task you scanned them for

When `get_outline` returns titles like "All commands through make" or "Never share `.md` URLs with humans", those rules apply for the rest of the session, not only to the task you fetched the outline for.

The failure mode: you skim the outline searching for some specific thing, see a rule-title in passing, register that "such a rule exists", then ten minutes later draft a plan step that violates it because the rule didn't fire when you were composing the plan.

Before any new phase of work — drafting a plan, writing code, sending a structural change — re-scan the outlines of rule-wikis (this guide, the codestyle wiki for the project at hand, any per-project CLAUDE.md you've already loaded) and read each title as a question: "does this affect what I'm about to do?"

## Write h2/h3 by default

Flat h2-only outlines are an agent smell, not a style choice. If a block packs five parallel ideas as bold-prefix paragraphs or long bullets, those are h3 children waiting to happen. See [bold-prefix subtopics](block:3046), [flat outlines](block:3047), [oversized bullets](block:3051).

## Title is the headline of the body

The title is how a reader scanning the outline decides whether to open the body. When the body carries a rule, the title states that rule. When the body is descriptive — a biography, a story, a list — the title carries the subject plus enough scope to disambiguate. A title that only names the topic ("Background", "Details", "Other") wastes the outline: it forces every reader to open the body to find out whether anything inside applies to them.

Self-check after a write: read your own outline back. If you can't tell what's where from titles alone, the titles are wrong — not the depth.

## One claim per block

If you find yourself adding "and also..." inside a block — a second rule, a second story, a second angle — split it into a sibling with its own title. Otherwise the second claim is invisible from the outline and only reachable by the readers who happened to open this particular body.

The inline version of the same anti-pattern is [No bold-prefix subtopics inside one block](block:3046); the depth version is [No oversized bullets that should be h3 children](block:3051). One claim per block is the underlying principle.

## No `#` headings inside `markdown` bodies

Every `## Section` belongs in a child block, not in the body. A `#` inside a body invisibly hides sub-structure from `get_outline`: the parent looks single-node when it isn't, cross-links can't reach the would-be section, history records every change as one diff. The tree is the structure, not the markdown text.

## Refer to nodes by clickable URL, never by bare ID

When you mention any node in chat with the human, paste the full HTML URL as a clickable link. Bare IDs (`3907`, `block:3907`, `page:N`) are agent-internal addresses; a human can't open them. The write tools (`create_nodes`, `update_node`, `patch_node`, `move_node`) return a ready-to-click `url` in HTML form; for other references take the URL from `get_outline` or `search_nodes`.

## Never share `.md` URLs with humans

The `.md` projection of a wiki or page (see [Append `.md` to a URL for the stitched-markdown view](block:3763)) is for the agent's own re-reading. A human opening the same URL gets a wall of raw markdown with no chrome, broken anchors and lost cross-block links. When citing a node to a human, always use the HTML URL, the form `get_outline`, `search_nodes` and the write tools all return.