# No comments

> For agents: start with the [agent guide](https://ratstack.sh/llms.txt). Every page is Markdown by default; add `Accept: text/html` for HTML.

New on /news: [tla-ts 0.0.9 adds TLC's -continue](/news).

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 fence](/lore/the-fence) for how the rule is enforced and [tests that earn their place](/lore/tests-that-earn-their-place) for the test that can replace a comment.

## Sources

1. [rat-stack/AGENTS.md at main · joelhooks/rat-stack · GitHub](https://github.com/joelhooks/rat-stack/blob/main/AGENTS.md)
   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](https://github.com/joelhooks/rat-stack/blob/main/scripts/oxlint-plugin-no-comments.ts)
   GitHub joelhooks/rat-stack. Comment lint rule; used for enforcement and prose removal. Accessed 2026-10-01.

## Linked from

- Agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms.txt)

- Change log → What changed in the files served here, newest first. → [Read page](https://ratstack.sh/log)

- Fence → Strict effect-tsrs diagnostics, lint, and hooks protect the gate; patched tsc checks compiler parity on checker bumps. → [Read page](https://ratstack.sh/systems/fence)

- Full agent guide → An Effect stack so pure (aspirational) Kit Langton will blush. → [Read page](https://ratstack.sh/llms-full.txt)

- Rat Stack lore | rat-stack → Short, source-grounded notes on the ideas and decisions behind rat-stack. → [Read page](https://ratstack.sh/lore)

- 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. → [Read page](https://ratstack.sh/lore/shitrat)

- 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. → [Read page](https://ratstack.sh/lore/shitrat-creed)

- 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. → [Read page](https://ratstack.sh/lore/shitrat-canon)

- Source change history (log.md) → The generated change log as Markdown. → [Read page](https://ratstack.sh/log.md)

- The fence → The fence uses compiler checks, lint rules, and hooks to reject unsafe shortcuts. → [Read page](https://ratstack.sh/lore/the-fence)

- The rat-stack bestiary eats excuses → A field guide to eight documented rat-stack creatures, with real habitats, enforceable behaviour, and strictly imaginary temperaments. → [Read page](https://ratstack.sh/lore/shitrat-bestiary)

## Unlinked mentions

- [Agent rules for rat-stack (AGENTS.md)](https://ratstack.sh/AGENTS.md) → No comments in code.