7 ms·

I've started giving these instructions and I think I've been much more successful in generating clear output: Comment blocks are <= 7 words, function names <=

I've started giving these instructions and I think I've been much more successful in generating clear output: Comment blocks are <= 7 words, function names <= 4 words. User-facing message strings should be <= 10 words. Use an active voice, no stage performances, and pick the most common word when choosing among alternatives. Limiting the number of words is the strongest factor in cleaning up the output, IMO. For older code I've instructed it to delete all the comments, and then I re-comment it using a new session and these guidelines, asking it to rejustify the need for every comment to itself.

vrosas 2mo ago
The problem is, when the context window grows, Claude tends to forget these kinds of rules. It will then do whatever it wants. I had to outright ban comments in the global claude.md, the local claude.md AND write a hook to catch any that still slipped through.
- mandeepj 2mo ago
  > The problem is, when the context window grows, You know the problem; then why not address it? Does Compacting the context not help?
  - troupo 2mo ago
    Compacting context compacts context. So Claude forgets a lot during compaction.
    - Maxatar 2mo ago
      Compacting mostly gets rid of reasoning tokens, and honestly it would be nice of reasoning tokens did not constantly follow every follow up query. Asking even a simple/trivial question can have Claude use thousands of tokens. Compacting is good for getting rid of those.
      - troupo 2mo ago
        I've had Claude immediately fall back to its usual verbose style immediately after compaction. To be fair, I've had it do that immediately after re-reading the output style instructions, too. My chat history is filled with "Yes, I broke the language rule. Let me rephrase that and update my memory. — You already have that in memory — Yes, true, I ignored that" (because "Memory" is a yet another .md file)
        strbean 2mo ago
        Claude Code supposedly supports a "post-compaction" hook, so you could have it automatically run the prompt "We just compacted the context, quickly refresh yourself on the rules in CLAUDE.md etc..". Depending on what you've got in those files, maybe that will just use up all the context again though.
        troupo 2mo ago
        > supposedly supports a "post-compaction" hook, so you could have it automatically run the prompt Keyword "supposedly" :) I've had it in my settings forever, and still... Asking it to analyse and fix the issue it produced a plausible "my training supercedes/overrides settings especially if triggered by certain words in the phrase" (paraphrasing the long text)
        strbean 2mo ago
        > Keyword "supposedly" :) > I've had it in my settings forever, and still... Checks out! I've never used it my self, so it I figured it likely didn't work at all.
  - adastra22 2mo ago
    Compacting the conversation almost never helps. It is uniformly worse than starting over with fresh context, or rewinding to a last-known-good state. It only exists because it increases engagement.
    - enraged_camel 2mo ago
      This does not match my experience. I use long-running orchestrator sessions. Each orchestrator is in charge of planning, writing kick-off prompts for implementers, answering questions from those implementers, doing code reviews and providing feedback, and answering side questions from me when I have them. Depending on the initiative I might compact a session a dozen times, sometimes more. It is lossy, and the session certainly tends to forget earlier bits as more compactions happen, but overall it's a much better experience than starting fresh and having to re-explain everything. The only time I compact is if the session goes wildly off-course and the context gets polluted with off-topic conversations. Also worth noting: with Claude Code you can provide custom instructions when compacting, and instruct the LLM that is in charge of compacting the session to prioritize the retention of specific bits. It can help a lot.
  - cautiouscat 2mo ago
    Compaction is a main cause of this problem.
- nater5000 2mo ago
  I think people really need to focus more on working with limited contexts rather than trying to work around it. I really try to keep my sessions as short as possible and it helps a ton with keeping Claude (et al) focused. Specifically, I like the "canary" trick that people have discussed where you add a small, innocuous rule to your CLAUDE.md like "When responding to me, start every sentence with my name." so that when Claude stops doing this, you know you've used way too much context and need to start a new session.
  - faizshah 2mo ago
    This or you just repeat the initial prompt every 200k tokens
    - ianjbutler 2mo ago
      Which gets you to the point where the whole thing is.. still unreliable. Generative text engines are going to generate. This calls for real enforcement in deterministic pre-edit hooks. And here is where naive people will say something like "Why do I care if robots shit all over the codebase? Code is for machines, I don't expect to deal with it much now". But really externalized CoT like this confuses machines too, wastes tokens, and eventually wastes exponentially many tokens. Agents tend to think it's more real grounding than prompts are, even for comments-in-code. One bad comment poisons everything, then gets copied around as a ground-truth assumption everywhere. Hooks are more real to them than prompts or comments, and even then if you add enforced limits and tell them to externalize CoT ONLY in scratch task-tracking docs.. they will violate comment-enforcement hooks about 25% of the time. That tells you everything you need to know: even with constant reinforcement, they just really want to break this kind of rule.
      - faizshah 2mo ago
        My take on this is they are a tool to help speed up your work they are not meant to produce finished work. Humans produce finished work. LLM will never be deterministic cause their entire value is that they are generalizable.
- aleksiy123 2mo ago
  Hooks is the way. Intermittent nudges
  - wheybags 2mo ago
    I have a post-edit hook that asks the model if this edit introduced any comments, and if it did, remove them. This was the only reliable way to get it to stop that I found.
- hectdev 2mo ago
  Yea, I've started making it write linters to check the code that goes out. Anything that can be deterministically measured, gets added to it once we lock it down.
kanzure 2mo ago
Yep. Same here. I frequently tell agents things like "answer using only a single sentence" and "write no more than 10 words". They are excellent at writing code, so have them write code (and not English prose). Besides, most of the time we want them to make reusable software that doesn't require users (or future agents) to read too much text. Software should generally just work and do the obvious thing, without needing verbose explanation.
graemep 2mo ago
Claude not only writes verbose comments, it also writes comments about how things used to work when refactoring. That might have a place in version control comments, but not in the code.
- nrmitchi 2mo ago
  I struggled with this for a long time, but actually seem to have gotten to a place where this is largely resolved. Copy/paste from my current claude.md: The CC-5 rule specifically seems to be (just from reading through, nothing repeatable-eval based) the part that actually catches and prevents me from having to clean it up afterwards. ``` ### Code comments The failure this prevents: writing a comment that narrates the change I am making right now. That context is real, but it expires the instant the change merges — the defect it describes no longer exists, so the comment becomes a story about a problem no future reader can observe. It is a changelog entry in the wrong file, and a third copy of text already required in the commit body (3.b) and the PR description. - *CC-1 (MUST NOT)* Write a comment describing a change, a fix, a defect, its cause, or what the code used to do. No "was/now/previously/instead of", no "this fixes", no "needed because otherwise", no "note that we no longer". - *CC-2 (MUST)* Apply the survival test to every comment before writing it: would this still be true and useful to someone reading this file a year from now, who never saw the diff? If it only makes sense beside the diff, it is changelog — delete it and put it in the commit body. - *CC-3 (MUST)* Default to zero comments. Declarative config — Terraform, DNS records, k8s manifests, CI YAML, Helm values — is self-describing and takes none. A resource named `dmarc-example-com` does not need a comment saying it is the DMARC record. - *CC-4 (MAY)* Comment only when a future editor would actively break something without it: a non-obvious external constraint, a required out-of-band manual step, an invariant the surrounding code cannot show. One line. If it needs a paragraph it belongs in `plans/`, not inline. - *CC-5 (MUST)* Before every commit, re-read the comment lines I added: `git diff --cached | grep '^+' | grep -E '#|//|/*'`. Each hit must pass CC-2 on its own. Deleting is always an acceptable outcome. "I already wrote it", "it is only one line", and "this one is genuinely useful" are not exemptions — the last one is the exact thought that precedes every violation. - *CC-6 (MUST)* Applies to comments I edit as well as ones I add. When a change invalidates an existing comment, the default action is DELETE, not rewrite it into a new narrative. ``` Yes, I am aware that claude mostly generated this, and it can probably be better and/or more succinct.
pbreit 2mo ago
Shouldn't this all be easily doable via (auto-)prompting? Surely I don't need to "install" anything?
transdev12 2mo ago
The corollary here is to have Claude write tests to enforce this. The only thing it is consistently responsive to is test failures.
nottorp 2mo ago
I just gave up and edit the comments manually. However, I've had a surprise today. I had it fix something then went and reduced one of the 3 line comments to 4 words. Then for some reason I told the bot to reload the source, it offered to make the other comments terse and did a passable job of it. Shocking! Now how to get it to do that all the time...
deleted 2mo ago
[deleted]
varispeed 2mo ago
Why it should write comments at all? Code is the documentation. I only let it write high level information of why something is the way it is.
SadErn 2mo ago
[dead]
lubujackson 2mo ago
I have extended this to coding work as well. "Implement this plan in less than 1000 added lines, tests included". It's amazing how well-behaved and concise models can be with simple guardrails. Of course, you have to intuit a reasonable line length, but Claude cries if you happen to clip its wings too aggressively.
millsau 2mo ago
So this works better then any other humanizer skill repo on github?

vrosas 2mo ago

The problem is, when the context window grows, Claude tends to forget these kinds of rules. It will then do whatever it wants. I had to outright ban comments in the global claude.md, the local claude.md AND write a hook to catch any that still slipped through.

mandeepj 2mo ago
> The problem is, when the context window grows, You know the problem; then why not address it? Does Compacting the context not help?
- troupo 2mo ago
  Compacting context compacts context. So Claude forgets a lot during compaction.
  - Maxatar 2mo ago
    Compacting mostly gets rid of reasoning tokens, and honestly it would be nice of reasoning tokens did not constantly follow every follow up query. Asking even a simple/trivial question can have Claude use thousands of tokens. Compacting is good for getting rid of those.
    - troupo 2mo ago
      I've had Claude immediately fall back to its usual verbose style immediately after compaction. To be fair, I've had it do that immediately after re-reading the output style instructions, too. My chat history is filled with "Yes, I broke the language rule. Let me rephrase that and update my memory. — You already have that in memory — Yes, true, I ignored that" (because "Memory" is a yet another .md file)
      - strbean 2mo ago
        Claude Code supposedly supports a "post-compaction" hook, so you could have it automatically run the prompt "We just compacted the context, quickly refresh yourself on the rules in CLAUDE.md etc..". Depending on what you've got in those files, maybe that will just use up all the context again though.
        troupo 2mo ago
        > supposedly supports a "post-compaction" hook, so you could have it automatically run the prompt Keyword "supposedly" :) I've had it in my settings forever, and still... Asking it to analyse and fix the issue it produced a plausible "my training supercedes/overrides settings especially if triggered by certain words in the phrase" (paraphrasing the long text)
        strbean 2mo ago
        > Keyword "supposedly" :) > I've had it in my settings forever, and still... Checks out! I've never used it my self, so it I figured it likely didn't work at all.
- adastra22 2mo ago
  Compacting the conversation almost never helps. It is uniformly worse than starting over with fresh context, or rewinding to a last-known-good state. It only exists because it increases engagement.
  - enraged_camel 2mo ago
    This does not match my experience. I use long-running orchestrator sessions. Each orchestrator is in charge of planning, writing kick-off prompts for implementers, answering questions from those implementers, doing code reviews and providing feedback, and answering side questions from me when I have them. Depending on the initiative I might compact a session a dozen times, sometimes more. It is lossy, and the session certainly tends to forget earlier bits as more compactions happen, but overall it's a much better experience than starting fresh and having to re-explain everything. The only time I compact is if the session goes wildly off-course and the context gets polluted with off-topic conversations. Also worth noting: with Claude Code you can provide custom instructions when compacting, and instruct the LLM that is in charge of compacting the session to prioritize the retention of specific bits. It can help a lot.
- cautiouscat 2mo ago
  Compaction is a main cause of this problem.
nater5000 2mo ago
I think people really need to focus more on working with limited contexts rather than trying to work around it. I really try to keep my sessions as short as possible and it helps a ton with keeping Claude (et al) focused. Specifically, I like the "canary" trick that people have discussed where you add a small, innocuous rule to your CLAUDE.md like "When responding to me, start every sentence with my name." so that when Claude stops doing this, you know you've used way too much context and need to start a new session.
- faizshah 2mo ago
  This or you just repeat the initial prompt every 200k tokens
  - ianjbutler 2mo ago
    Which gets you to the point where the whole thing is.. still unreliable. Generative text engines are going to generate. This calls for real enforcement in deterministic pre-edit hooks. And here is where naive people will say something like "Why do I care if robots shit all over the codebase? Code is for machines, I don't expect to deal with it much now". But really externalized CoT like this confuses machines too, wastes tokens, and eventually wastes exponentially many tokens. Agents tend to think it's more real grounding than prompts are, even for comments-in-code. One bad comment poisons everything, then gets copied around as a ground-truth assumption everywhere. Hooks are more real to them than prompts or comments, and even then if you add enforced limits and tell them to externalize CoT ONLY in scratch task-tracking docs.. they will violate comment-enforcement hooks about 25% of the time. That tells you everything you need to know: even with constant reinforcement, they just really want to break this kind of rule.
    - faizshah 2mo ago
      My take on this is they are a tool to help speed up your work they are not meant to produce finished work. Humans produce finished work. LLM will never be deterministic cause their entire value is that they are generalizable.
aleksiy123 2mo ago
Hooks is the way. Intermittent nudges
- wheybags 2mo ago
  I have a post-edit hook that asks the model if this edit introduced any comments, and if it did, remove them. This was the only reliable way to get it to stop that I found.
hectdev 2mo ago
Yea, I've started making it write linters to check the code that goes out. Anything that can be deterministically measured, gets added to it once we lock it down.

kanzure 2mo ago

Yep. Same here. I frequently tell agents things like "answer using only a single sentence" and "write no more than 10 words". They are excellent at writing code, so have them write code (and not English prose). Besides, most of the time we want them to make reusable software that doesn't require users (or future agents) to read too much text. Software should generally just work and do the obvious thing, without needing verbose explanation.

graemep 2mo ago

Claude not only writes verbose comments, it also writes comments about how things used to work when refactoring. That might have a place in version control comments, but not in the code.

nrmitchi 2mo ago
I struggled with this for a long time, but actually seem to have gotten to a place where this is largely resolved. Copy/paste from my current claude.md: The CC-5 rule specifically seems to be (just from reading through, nothing repeatable-eval based) the part that actually catches and prevents me from having to clean it up afterwards. ``` ### Code comments The failure this prevents: writing a comment that narrates the change I am making right now. That context is real, but it expires the instant the change merges — the defect it describes no longer exists, so the comment becomes a story about a problem no future reader can observe. It is a changelog entry in the wrong file, and a third copy of text already required in the commit body (3.b) and the PR description. - *CC-1 (MUST NOT)* Write a comment describing a change, a fix, a defect, its cause, or what the code used to do. No "was/now/previously/instead of", no "this fixes", no "needed because otherwise", no "note that we no longer". - *CC-2 (MUST)* Apply the survival test to every comment before writing it: would this still be true and useful to someone reading this file a year from now, who never saw the diff? If it only makes sense beside the diff, it is changelog — delete it and put it in the commit body. - *CC-3 (MUST)* Default to zero comments. Declarative config — Terraform, DNS records, k8s manifests, CI YAML, Helm values — is self-describing and takes none. A resource named `dmarc-example-com` does not need a comment saying it is the DMARC record. - *CC-4 (MAY)* Comment only when a future editor would actively break something without it: a non-obvious external constraint, a required out-of-band manual step, an invariant the surrounding code cannot show. One line. If it needs a paragraph it belongs in `plans/`, not inline. - *CC-5 (MUST)* Before every commit, re-read the comment lines I added: `git diff --cached | grep '^+' | grep -E '#|//|/*'`. Each hit must pass CC-2 on its own. Deleting is always an acceptable outcome. "I already wrote it", "it is only one line", and "this one is genuinely useful" are not exemptions — the last one is the exact thought that precedes every violation. - *CC-6 (MUST)* Applies to comments I edit as well as ones I add. When a change invalidates an existing comment, the default action is DELETE, not rewrite it into a new narrative. ``` Yes, I am aware that claude mostly generated this, and it can probably be better and/or more succinct.

pbreit 2mo ago

Shouldn't this all be easily doable via (auto-)prompting? Surely I don't need to "install" anything?

transdev12 2mo ago

The corollary here is to have Claude write tests to enforce this. The only thing it is consistently responsive to is test failures.

nottorp 2mo ago

I just gave up and edit the comments manually. However, I've had a surprise today. I had it fix something then went and reduced one of the 3 line comments to 4 words. Then for some reason I told the bot to reload the source, it offered to make the other comments terse and did a passable job of it. Shocking! Now how to get it to do that all the time...

deleted 2mo ago

[deleted]

varispeed 2mo ago

Why it should write comments at all? Code is the documentation. I only let it write high level information of why something is the way it is.

SadErn 2mo ago

[dead]

lubujackson 2mo ago

I have extended this to coding work as well. "Implement this plan in less than 1000 added lines, tests included". It's amazing how well-behaved and concise models can be with simple guardrails. Of course, you have to intuit a reasonable line length, but Claude cries if you happen to clip its wings too aggressively.

millsau 2mo ago

So this works better then any other humanizer skill repo on github?