AGENTS.md: keep comments minimal; propose a docs page instead #55

Merged

pit merged 1 commit from hermes/55-agents-comments into main

2026-10-07 16:45:33 +00:00

pit commented

2026-10-07 16:44:58 +00:00

Owner

Summary

A new rule in AGENTS.md, under ## Rules, alongside Secrets and Privacy:

 ## Rules
 ### Secrets
 ### Privacy
+### Code comments
+
+Keep comments to a minimum: code should be expressive enough to explain itself.
+When something genuinely needs more explanation than the code can carry, propose
+a docs page under `docs/` instead of writing it as a comment.
 
 ## Docs

One file, one hunk, 6 added lines. No source, no Target, no infra touched.

Evidence

AGENTS.md is read by an Agent at the start of a session; there is nothing to
rehearse on PRE, and no acceptance criterion in an issue to exercise — the
change was Operator-requested in session, with no tracker issue behind it.

What was run:

make fmt in the worktree → tofu fmt -recursive, clean; only AGENTS.md
modified, no source reformatted.
git show --stat HEAD → AGENTS.md | 6 ++++++, 1 file changed, 6 insertions.

Merge Danger

Door: two-way. A rule in a Markdown file; reverting is one commit.

Blast radius: repo-wide convention, and it collides with what is already
there. The Makefile and docs/wiki-pages.yml are written as long explanatory
comment blocks — the exact shape the rule now discourages. The rule as worded
binds new code; whether the existing comments get trimmed, or are grandfathered
as "the explanation of what each Target does", is a decision this PR does not
make. Flagging rather than deciding.

## Summary A new rule in `AGENTS.md`, under `## Rules`, alongside Secrets and Privacy: ```diff ## Rules ### Secrets ### Privacy +### Code comments + +Keep comments to a minimum: code should be expressive enough to explain itself. +When something genuinely needs more explanation than the code can carry, propose +a docs page under `docs/` instead of writing it as a comment. ## Docs ``` One file, one hunk, 6 added lines. No source, no Target, no infra touched. ## Evidence `AGENTS.md` is read by an Agent at the start of a session; there is nothing to rehearse on PRE, and no acceptance criterion in an issue to exercise — the change was Operator-requested in session, with no tracker issue behind it. What was run: - `make fmt` in the worktree → `tofu fmt -recursive`, clean; only `AGENTS.md` modified, no source reformatted. - `git show --stat HEAD` → `AGENTS.md | 6 ++++++`, 1 file changed, 6 insertions. ## Merge Danger **Door:** two-way. A rule in a Markdown file; reverting is one commit. **Blast radius:** repo-wide convention, and it collides with what is already there. The Makefile and `docs/wiki-pages.yml` are written as long explanatory comment blocks — the exact shape the rule now discourages. The rule as worded binds new code; whether the existing comments get trimmed, or are grandfathered as "the explanation of what each Target does", is a decision this PR does not make. Flagging rather than deciding.

pit added 1 commit

2026-10-07 16:44:58 +00:00

AGENTS.md: keep comments minimal; propose a docs page instead bf4c1afdc2

The Rules section gains a Code comments rule: code should be expressive
enough to explain itself, and anything that still needs explaining is a
signal to propose a docs page under docs/ rather than write a comment.

No issue behind this; Operator-requested.

pit merged commit d38e0cdfec into main

2026-10-07 16:45:33 +00:00

pit deleted branch hermes/55-agents-comments

2026-10-07 16:45:33 +00:00

pit referenced this pull request from a commit

2026-10-07 16:45:34 +00:00

AGENTS.md: keep comments minimal; propose a docs page instead (#55)