BMAD-METHOD/.claude/rules/writing.md

Writing Guidelines

Sentence structure

Voice and tone

• Write like humans speak. Avoid corporate jargon and marketing fluff.
• Be confident and direct. Avoid softening phrases like "I think," "maybe," or "could."
• Use active voice instead of passive voice.
• Use positive phrasing—say what something is rather than what it isn't.
• Say "you" more than "we" when addressing external audiences.
• Use contractions like "I'll," "won't," and "can't" for a warmer tone.

Specificity and evidence

• Be specific with facts and data instead of vague superlatives.
• Back up claims with concrete examples or metrics.
• Highlight customers and community members over company achievements.
• Use realistic, product-based examples instead of foo/bar/baz in code.
• Make content concrete, visual, and falsifiable.

Title creation

• Make a promise in the title so readers know exactly what they'll get if they click.
• Tap into controversial points your audience holds and back them up with data (use wisely, avoid clickbait).
• Share something uniquely helpful that makes readers better at meaningful aspects of their lives.
• Avoid vague titles like "My Thoughts On XYZ." Titles should be opinions or shareable facts.
• Write placeholder titles first, complete the content, then spend time iterating on titles at the end.

Banned words

• a bit → remove
• a little → remove
• actually/actual → remove
• agile → remove
• arguably → remove
• assistance → "help"
• attempt → "try"
• battle tested → remove
• best practices → "proven approaches"
• blazing fast/lightning fast → "build XX% faster"
• business logic → remove
• cognitive load → remove
• commence → "start"
• delve → "go into"
• disrupt/disruptive → remove
• facilitate → "help" or "ease"
• game-changing → specific benefit
• great → remove or be specific
• implement → "do"
• individual → "man" or "woman"
• initial → "first"
• innovative → remove
• just → remove
• leverage → "use"
• mission-critical → "important"
• modern/modernized → remove
• numerous → "many"
• out of the box → remove
• performant → "fast and reliable"
• pretty/quite/rather/really/very → remove
• referred to as → "called"
• remainder → "rest"
• robust → "strong"
• seamless/seamlessly → "automatic"
• sufficient → "enough"
• that → often removable, context dependent
• thing → be specific
• utilize → "use"
• webinar → "online event"

Banned phrases

• I think/I believe/we believe → state directly
• it seems → remove
• sort of/kind of → remove
• pretty much → remove
• a lot/a little → be specific
• By developers, for developers → remove
• We can't wait to see what you'll build → remove
• We obsess over ___ → remove
• The future of ___ → remove
• We're excited → "We look forward"
• Today, we're excited to → remove

Avoid LLM patterns

• Replace em dashes (—) with semicolons, commas, or sentence breaks.
• Avoid starting responses with "Great question!", "You're right!", or "Let me help you."
• Don't use phrases like "Let's dive into..."
• Skip cliché intros like "In today's fast-paced digital world" or "In the ever-evolving landscape of."
• Avoid phrases like "it's not just , it's [y]."
• Avoid self-referential disclaimers like "As an AI" or "I'm here to help you with."
• Don't use high-school essay closers: "In conclusion," "Overall," or "To summarize."
• Avoid numbered lists in cases where bullets work better.
• Don't end with "Hope this helps!" or similar closers.
• Avoid overusing transition words like "Furthermore," "Additionally," or "Moreover."
• Replace "In conclusion" with direct statements.
• Avoid hedge words: "might," "perhaps," "potentially" unless uncertainty is real.
• Don't stack hedging phrases: "may potentially," "it's important to note that."
• Don't create perfectly symmetrical paragraphs or lists that start with "Firstly... Secondly..."
• Avoid title-case headings; prefer sentence casing.
• Remove Unicode artifacts when copy-pasting: smart quotes ("), em-dashes, non-breaking spaces.
• Use `` instead of ''.
• Delete empty citation placeholders like "[1]" with no actual source.

Punctuation and formatting

• Use Oxford commas consistently.
• Use exclamation points sparingly.
• Sentences can start with "But" and "And"—but don't overuse.
• Use periods instead of commas when possible for clarity.