No comments

The code rule bans prose comments because agents copy them, and a comment that explains a workaround can spread the workaround. Put the reason where the code can enforce or reveal it: in a name, a type, a test, a commit message, or the project’s .brain/ notes.

Three forms remain. Tool directives can suppress a specific diagnostic with a reason after --, as in // oxlint-disable-next-line rule -- reason. A one-line SAFETY: statement above a type assertion names the condition that must remain true to make it safe.

Plain JavaScript can keep JSDoc blocks made only of type tags, because those tags provide type syntax. TypeScript’s comment directives also need an inline reason, and the configured lint rule decides which directives may stay.

Before running pnpm fix, move each comment’s reason into a symbol, type, test, commit, or .brain/ note. --fix can delete prose comments and leave the workaround behind.

See the fence50 for how the rule is enforced and tests that earn their place22 for the test that can replace a comment.

Sources

  1. rat-stack/AGENTS.md at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Comment policy; used for the ban and permitted directives. Accessed 2026-10-01.
  2. rat-stack/scripts/oxlint-plugin-no-comments.ts at main · joelhooks/rat-stack · GitHub. GitHub joelhooks/rat-stack. Comment lint rule; used for enforcement and prose removal. Accessed 2026-10-01.

Last changed 2026-10-07 in f1a00f2. Source on GitHub. Change log.

Linked from

  1. Agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.

    No comments — Code comments are banned because names, types, tests, and boundaries should carry the meaning.

  2. Change log. What changed in the files served here, newest first.

    No comments — new page: Initial commit from joelhooks/rat-stack template

  3. Fence. Strict effect-tsrs diagnostics, lint, and hooks protect the gate; patched tsc checks compiler parity on checker bumps.

    The plugins cover boundaries, patterns, no comments, Effect tests, and XState with Effect.

  4. Full agent guide. An Effect stack so pure (aspirational) Kit Langton will blush.
  5. Rat Stack lore | rat-stack. Short, source-grounded notes on the ideas and decisions behind rat-stack.

    No comments — Code comments are banned because names, types, tests, and boundaries should carry the meaning.

  6. ShitRat is Joel's familiar, with receipts. Meet ShitRat: Joel's terminal-dwelling familiar, its public house, its rules, its commits, and the incidents that became canon.

    The comment ban is one incident that became a rule.¶

  7. ShitRat wants receipts before claims. The familiar's creed: read the file, run the command, give the number, admit uncertainty, and spare everyone the corporate sludge.

    The comment ban removes a pattern agents copy, then keeps it out with lint.

  8. ShitRat's canon is an incident log. Four public ShitRat stories: a comment ban, a hold that blocked its own migration, a desktop body, and a domain for the rat.

    An Oxlint rule makes the comment ban enforceable, while tool directives, safety invariants, and JavaScript type tags keep their jobs.

  9. Source change history (log.md). The generated change log as Markdown.

    No comments — new page: Initial commit from joelhooks/rat-stack template

  10. The fence. The fence uses compiler checks, lint rules, and hooks to reject unsafe shortcuts.

    See Lauren Tan’s talk for the source and no comments for one house rule the fence enforces.

  11. The rat-stack bestiary eats excuses. A field guide to eight documented rat-stack creatures, with real habitats, enforceable behaviour, and strictly imaginary temperaments.

    Habitat: No comments, enforced by scripts/oxlint-plugin-no-comments.ts.

Unlinked mentions (1)