Skip to content

CLAUDE.md

Latest commit

 

History

History
105 lines (84 loc) · 5.49 KB

CLAUDE.md

File metadata and controls

105 lines (84 loc) · 5.49 KB
Raw

Project: PostGuard Docs

VitePress documentation site. Run npm run docs:dev to preview locally.

Code Snippets

Code examples in the docs must come from real, working code. Do not invent example code.

Snippets are pasted inline as fenced code blocks with a <small> source link underneath pointing to the exact file and lines on GitHub. The link must use a full commit hash so the content is pinned.

Source repositories:

  • encryption4all/postguard-examples (SvelteKit web app example)
  • encryption4all/postguard-tb-addon (Thunderbird addon)
  • encryption4all/postguard-outlook-addon (Outlook addon)

When adding or updating a snippet:

  1. Fetch the file from the raw GitHub URL using a specific commit hash: https://raw.githubusercontent.com/encryption4all/REPO/COMMIT_HASH/path/to/file.ts
  2. Copy the relevant lines into a fenced code block with the correct language tag.
  3. Add a source link directly below the code block: <small>[Source: filename.ts#L20-L31](https://github.com/encryption4all/REPO/blob/COMMIT_HASH/path/to/file.ts#L20-L31)</small>

Keep snippets focused. Only include the lines that are relevant to the surrounding prose. Do not paste entire files when a 10-30 line extract will do.

Writing Style Rules

All written content in this project must sound like a competent human wrote it. Follow these rules strictly when writing or editing any prose (markdown, comments, UI copy).

Banned Words (always replace)

  • "delve" / "delve into" -> explore, dig into, look at
  • "leverage" -> use
  • "utilize" -> use
  • "robust" -> strong, reliable, solid
  • "comprehensive" -> thorough, complete
  • "seamless" -> smooth, easy
  • "cutting-edge" -> latest, newest
  • "pivotal" -> important, key
  • "embark" -> start, begin
  • "landscape" -> field, space, area
  • "tapestry" -> describe the actual complexity
  • "realm" -> area, field, domain
  • "paradigm" -> model, approach
  • "testament to" -> shows, proves
  • "serves as" -> is
  • "boasts" -> has
  • "in order to" -> to
  • "due to the fact that" -> because
  • "it's important to note" -> cut entirely or just state the thing
  • "it's worth mentioning" -> cut entirely
  • "harness" -> use
  • "empower" -> let, allow, help
  • "foster" -> build, encourage
  • "elevate" -> improve, raise
  • "streamline" -> simplify
  • "holistic" -> complete, full
  • "actionable" -> practical, useful
  • "impactful" -> effective
  • "synergy" -> describe the combined effect directly
  • "ecosystem" -> system, community, tooling
  • "myriad" -> many
  • "plethora" -> many, plenty
  • "transformative" -> say what changed
  • "cornerstone" -> foundation, base, key part
  • "deep dive" -> examine, explore
  • "unpack" -> explain, break down
  • "game-changer" -> say why it matters
  • "genuinely" -> cut or use "really" sparingly

Banned Transitions

Do not start sentences with: "Moreover," "Furthermore," "Additionally," "Indeed," "Notably," "Consequently," "Subsequently," "Accordingly." Use plain conjunctions (and, but, so, yet) or just start a new sentence.

Structural Rules

  • No "It's not X -- it's Y" contrast framing. Make a direct positive statement instead.
  • No significance inflation ("marking a pivotal moment," "watershed moment"). State what happened. Let the reader judge importance.
  • No rhetorical question openers ("But what does this mean?" / "Why should you care?"). If you know the answer, state it.
  • No generic conclusions ("The future looks bright," "Only time will tell," "One thing is certain"). End with something specific or just stop.
  • No mechanical rule of three ("efficient, effective, and reliable"). One or two descriptors is usually enough.
  • No synonym cycling. If "developers" is the right word, keep using "developers." Don't rotate through "engineers... practitioners... builders."
  • No chatbot artifacts ("Certainly!", "Great question!", "I hope this helps!", "Feel free to reach out", "Let's dive in").
  • No "Let's" constructions ("Let's explore," "Let's break this down"). Start with the point.
  • No "-ing" chains ("highlighting... emphasizing... facilitating..."). Replace with specific facts.
  • No false concession structure ("While X is impressive, Y remains a challenge") unless the concession is specific and earned.
  • No vague specificity ("various factors," "a range of considerations"). Name the things or cut.

Formatting Rules

  • Em dashes: target zero. Hard max one per 1,000 words. Use commas, periods, or parentheses instead.
  • Bold: target zero. Hard max one per 1,000 words. Do not bold for emphasis in running prose.
  • Bullet lists: use only when listing genuinely parallel items (API parameters, config options, steps). Never use lists as a substitute for writing a paragraph. Prose is the default.
  • Headers: don't over-nest. H2 and H3 are usually enough.
  • Colons in titles: avoid ("PostGuard: The Future of Email Security" -> "PostGuard protects your email" or just "PostGuard").

Voice

  • Use plain, direct English. Prefer common words over elevated ones.
  • Use "is" and "are" freely. Do not avoid simple verbs.
  • Write with calm authority. Assume the reader is competent.
  • State claims directly without excessive hedging ("perhaps," "it could be argued") unless genuine uncertainty exists.
  • Have a point of view. Don't balance every argument with a counterargument.
  • Vary sentence length. Include some short sentences. Not every sentence needs a subordinate clause.
  • Specific over vague. Name tools, functions, files, and versions. "Use the verify() method" not "use the appropriate verification mechanism."
  • Keep stakes proportional to the subject matter. Documentation is helpful, not revolutionary.