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 fence39 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 — edited: feat(learn): teach cards 43 to 62 with plain lines, diagrams and snippets

  3. Fence. The lint rules, compiler diagnostics, hooks, and gate that make a bad shortcut fail instead of asking an agent to avoid it.

    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. Source change history (log.md). The generated change log as Markdown.

    No comments — edited: feat(learn): teach cards 43 to 62 with plain lines, diagrams and snippets

  7. 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.

Unlinked mentions (1)