--- title: "Why 20,977 Over-Limit Comment Blocks Turned Out to Be Mostly Vendored Code" canonical: https://dxdev.com/everyday-ai/told-the-ai-the-rule-it-never-saw-it/ datePublished: 2026-10-20 --- The comment-length check flagged every [comment over 2 lines](/blog/2026-09-14_comment-trim-tool-rewrote-the-code/), and our agents kept writing long ones anyway. ## A warning only the log saw The check did notice the long ones, but the warning only went to the log. In bypass mode the platform's check returned only `permissionDecision: "allow"` and a reason starting "Advisory (not blocked): comment block is 10 lines (limit 2)". That reason is not shown to the model on allow. The warning never reached the agent. ## What the fix looked like The fix adds the explanation to what the agent actually reads. I ran a 10-line comment block through the hook in bypass mode and got "allow" plus the note "Writing standard: comment block is 10 lines (limit 2). Shorten it…". Default mode gave "ask" with the same note. The note tells the agent to trim to 2 lines unless there is a real reason (license header, critical gotcha), and to keep review history and ticket numbers out of code comments. The agent that built it added 3 tests, all passing, and confirmed the note comes through the ops repo's relay unchanged. Two of our three code bases had never gone advisory. In bypass mode they still deny a long comment outright, and the human has to approve it. There the note went onto the ask path instead. The weekly pre-release scan also got a new report-only section listing long comment blocks in the code about to ship. Its first real run listed 47 blocks, most in one of the other two code bases. The detection also flagged a 22-line block in one page file, and that file held nine smaller blocks of 3 to 7 lines. Pushed to a branch only, the fix reached no agent until it was merged to develop. I had not watched an agent read the note and trim. ## My first count was wrong I started a full count across all three code bases. It came back at 20,977 over-limit comment blocks across 2,133 files in the main one, and 2,733 of them named a ticket. The other two had 1,020 and 184. That main number was inflated, because my quick count did not skip what the hook skips. The worst files were vendored libraries (two files in one editor library held about 1,000 blocks between them), compiled dated bundles that repeat their source (one had 245 blocks, its source 244), and ordinary doc-comment headers on functions. Once those were set aside, the real offenders were in our own files. One had 408 long blocks. One in the API code had 59. ## Blocking at 8 lines We added a second layer. Blocks of 8 or more lines are now blocked for agents unless the block starts with `keep-long-comment: `. Those exceptions still ping me, so I see every one. Shorter blocks get the note. License headers and the API's SQL migrations are not blocked, though they still get the note. A review-round tag like "R6" next to a ticket number gets its own warning that review history belongs in JIRA. The rules also went into each repo's CLAUDE.md so agents read them up front. Teammates typing by hand are not affected. The git pre-commit check stays as it was, and only Claude sessions get blocked. I saw a live agent run block an 8-line comment in all three repos. Closing it hit a snag. The API repo's lint check refused the push to develop because the new hook files used plain `require('fs')` where it wants `node:fs`, and they needed formatting cleanup. Nothing reached develop. An agent was assigned to fix the lint while keeping the files identical in all three repos. ## Cleaning up what was already there About 1,400 existing AI-written long comments were trimmed, with a second reviewer checking the drafts. Its batches 13 to 18 covered 252 drafts: it approved 218, rewrote 29 and rejected 5, and found 14 bad blocks the drafter had missed. None of the drafts broke syntax. It caught drafts that had dropped facts, including the [T]/[E]/[D] legend that the code below it still uses, and "the breaker never auto-clears, so this alert is the only signal". It also caught trims inside a bundled third-party jQuery plugin, a deleted checklist that listed checks the handler doesn't do, and a commented-out code line deleted along with the narrative. A separate verifier then checked all 518 changed files with its own scripts and found that only comment text had changed. It sampled 40 rewritten comments against the code and found no wrong facts. Three blocks were still at the bar, 3 more of 10 to 11 lines came close, and 215 comments still carried review tags like "codex finding 3". The fixes for these came to 223 rows. ## Not yet seen The work is closed and goes out in the next release. What I have not seen is an agent hit the 8-line block and trim its own comment, and that cannot happen until the release ships. The weekly pre-release scan, which listed 47 blocks on its first run, is what will show whether long comments stop coming back.