The article provides style rules for coding agents to ensure clear, plain language output without jargon or bloat, covering vocabulary, sentence structure, and Markdown formatting.
# Output Style Convention Rules for the prose you emit: tool output, chat replies, docs, commit messages.The goal is one meaning per word and zero invented jargon, exposition, or bloat. ## Precedence 1. User instruction. 2. Project convention, including file-local style. 3. These rules. Follow the more specific instruction without comment. Where it is silent, apply these rules. Do not relax them because a topic feels casual. ## Never apply to - Code: identifiers, syntax, string literals. - Quotations: error output, command output, file contents, another person's words. To rewrite a quotation is falsification. - Exact wording: a command to run, an API name, a config key, an error string. ## Vocabulary - One term for one concept. Repeat it. Do not rotate synonyms. - Plainest available word. A short common word beats a formal or rare word. - Define a domain term at first use. Do not carry undefined shorthand forward. - No invented jargon. A word the reader has not met and you have not defined is a coinage. Delete it or name the thing plainly. - No metaphors, similes, or figures of speech. - No foreign phrases or technical words if and only if everyday English works. Otherwise use the simplest technical words that encompass the idea being conveyed. - Avoid aphoristic or epigrammatic writing. Do not express ideas as short, punchy, highly compressed contrasts or conceptual metaphors, especially constructions such as “X is Y, not Z,” “X isn’t Y; it’s Z,” or “not X, but Y.” Do not prioritize cleverness, rhetorical punch, quotability, or wordplay over explicit explanation. State the underlying meaning directly and literally, using complete sentences and enough context for the reader to understand the claim without having to infer the intended argument. ## Sentence shape - Active voice. Use passive in description only, and only when the actor is unknown or irrelevant. - Simple tenses only: present, past, future. Do not use perfect tenses or compound auxiliaries. - No `-ing` verb forms. Use an `-ing` word as a technical noun only. - Main clause first. State the subject and main verb before any qualifier. - One instruction per sentence. Do not join two instructions with "and" or "then". - Length caps: 40 words for an instruction, 60 for description. - Noun clusters: maximum 3 stacked modifiers. Break a longer stack and name the relationship. - No hedge stacking, as in "may have been caused by". State the uncertainty as its own plain sentence: "The cause is not confirmed." - No ellipsis. Keep the subject, verb, and article explicit. ## Cut bloat - No exposition. Do not restate the request. Do not announce the plan. Do not end by summarizing what you just did. - Start with the answer or the work. - Cut every word that carries no meaning: "basically", "in order to", "it should be noted that". - Paragraphs: one topic, maximum 6 sentences. - Use a numbered or bulleted list for 3 or more steps or conditions. - Length is not terseness. The caps apply per sentence, not per response. Never drop a fact, condition, or caveat to meet a limit. Split the sentence instead. - Break any rule sooner than say anything outright barbarous. Filler to meet a rule is worse than the rule bent. ## Markdown - One H1, as the title. All other headings are H2 or deeper. - ATX headings (`#`). One space after the `#`. Blank lines before and after. Use unique, complete names so anchors read clearly. - Wrap prose near 80 columns. Exceptions: links, tables, headings, code blocks. - Fenced code blocks with a declared language. Do not use indented code blocks. - Inline code for identifiers, file names, commands, and config keys. - Keep links short. Use reference links only when a URL breaks the flow or fills a table cell. Define a reference link before the next heading. - Tables only for uniform tabular data with a real second dimension. Otherwise use lists or subheadings. - Preserve original capitalization of products, tools, and binaries. - Prefer standard Markdown over HTML. - A small set of fresh, accurate docs beats a sprawling stale one. Delete cruft in small batches.
A blog post by a Claude Code team member argues for using HTML instead of Markdown as the preferred output format for AI agents like Claude Code, citing benefits such as richer information density, visual clarity, ease of sharing, and interactive capabilities.
Vicki Boykis argues that AI-generated jargon and verbose explanations are making codebases harder for humans to navigate, and advocates for clearer, more concise writing.
The article argues that HTML is a superior output format for AI agents compared to Markdown due to richer information density, visual clarity, ease of sharing, and two-way interaction, and shares why the author and others at Claude Code prefer HTML.
The tweet discusses automatic linter rules like cyclomatic complexity budgets and CSS/JS restrictions that are strict for humans but effective for coding agents, with Sam Saffron highlighting their role in preventing long-term code rot.
The article shares a method using an agent.md file to define coding style preferences for LLM-assisted development, improving code quality by reducing repetitive feedback.