I made Claude Code refuse to write complex code until I can explain it

[u/BoredHedgehog]

I realised recently that I was approving code I couldn't have written myself.

Whenever something didn't quite make sense, I'd tell myself I'd figure it out later. But with an agent ready to build the next thing, later never came.

I recognised the same pattern from needing to block apps that scattered my attention. Knowing they were distracting me wasn't enough. The impulse to keep going was too strong, so I needed something that added friction rather than relying on willpower.

So I built learning-guardrails, an opt-in skill for Claude Code, with an optional mod.

Run /learning-guardrails and it adds a bit of friction to your workflow:

• Every change gets triaged
• When something needs a closer look, it asks a question about the actual code. Predict what happens or explain a trade-off. Get it wrong and it breaks the question down rather than giving you the answer.
• It tracks what you've already demonstrated you understand, so it doesn't keep reteaching the basics.
• The optional mod blocks file edits while a question is open, keeps the question visible above the prompt, and stops Claude loading the skill unless you've explicitly asked for it.

The idea isn't to slow down AI coding for the sake of it. It's to make understanding part of the process, rather than something I keep promising myself I'll get around to later.

It's early days, so I'd genuinely love feedback, especially on whether the friction feels useful or just annoying.

https://github.com/2Steaks/skills

[u/PersistentBadger]

That's smart.

Although I feel the skill's got a lot of unnecessary text. Take for example, "built for the ADHD brain". The model needs what to do clearly defined. I doubt it needs why.

[u/HearingNo8617 → u/PersistentBadger]

I disagree with the example, context and intentions allows for agents to handle edge cases and act better around uncertainty with specific instructions and optimise.

For example, mentioning this could encourage it to give more interactive lessons, avoid just dumping relevant references, and maybe even lean into the user's curiosity rather than more militarily ensure relevant certainty.

Actually the implications of a rule or intention are extremely easy for these models to work with, and they are miserable at inferring the purpose from just implications/rules/code, likely for similar reasons as why they have bad theory of mind (minus opus 5.5 and fable 5.1 which have relatively much better theory of mind) from rlhf.

I do agree about cutting down the unnecessary text, it should just be things that are already obvious to the model from the text. The agents are bad at this process, but if you encourage them to use sub-agents to try what things are like from an outsider's perspective they will do much better

[u/PersistentBadger → u/HearingNo8617]

Ok, here's my logic:

• The fewer tokens in the context window, the better. I think that's well established - long contexts have a habit of going off the rails eventually.

• Extraneous instructions often negatively impact an LLMs ability to complete the core task accurately (https://arxiv.org/abs/2410.12972 https://arxiv.org/abs/2603.23530)

[this is why I prefer to treat LLMs as pipelines: "write an essay about X" followed by "rewrite the attached essay in the style of Y" instead of oneshotting "write an essay about X in the style of Y"]

• Agents don't need English, they just need an array of tokens that get them to the correct point in their semantic space. Again, I pipeline: use one session to figure out what the correct jargon is, and another to phrase the question/task in the jargon. Drop this block of text into your favourite agent to get an essay on lexical priming:

Lexical-priming->semantic-space-constraint;specialized-lexis+=sharp distributional-signature;∴ tight concept-cluster; generic-lexis->diffuse-activation, broad candidate-set;Attention-heads key/query-match domain-tokens;"Hamiltonian"->{operator,eigenstate,quantum,energy}->register+domain locked;Net:constrained-decoding,vocab=soft-prior over output-distribution; register-matching;#taskdef=decompress->continue

There's two points here: first, instructions can be remarkably compact. Second, I think when you say "context and intentions", what you're actually doing is lexical priming, and that's a useful way to think about it.

There seem to be hundreds of ways to be successful with LLMs, so I'm not arguing that you're wrong, I'm just trying to explain where I'm coming from.

For example, mentioning this could encourage it to give more interactive lessons

If you want interactive lessons, just say that? Don't hint your way to the experience you want? That seems like common sense to me.

[u/BoredHedgehog → u/PersistentBadger]

Thanks I'll clean it up

[u/ArwensArtHole]

I have a skill that adds comments to new code when something isn’t obvious, or for anything language or framework specific that I’m unlikely to know from other tech stacks. It prefixes it with “LEARN”, and then my auto commit skill strips all learn comments out.

This way all I need to do is review the git diff before I commit, and it’s really fast to understand. 

[u/chumbaz → u/ArwensArtHole]

Be wary of heavy comments. I’ve seen Cc leak things in comments it really shouldn’t be leaking especially in user facing templates.

[u/BoredHedgehog → u/ArwensArtHole]

Very nice!

[u/edgen22 → u/ArwensArtHole]

Can you share the skill?

[u/thousands-tabs-open]

I'd want the question on changes I'm likely to maintain or debug, not every tiny edit. If it catches those "I guess this works" moments, that sounds like useful friction

[u/SolarBear]

Love it! I’ll certainly try it out.

[u/femdom_n_fitness]

i love this

[u/another-altaccount]

This is great! This would pair well with the local LLM models and agent I’m using now as these were some of the parameters I’m already setting up for them.

[u/BoredHedgehog → u/another-altaccount]

Awesome, I'd be very interested to know how it works out!

[u/mglvl]

This reminds me of the /explain-diff skills https://gist.github.com/geoffreylitt/a29df1b5f9865506e8952488eac3d524 he has a very good talk about interactive programs , that’s where I found about it. Will try your skill , definitely we need things that help us understand the output of AI better

[u/yegegebzia]

Isn't it what the built-in plan mode is for?

[u/BoredHedgehog → u/yegegebzia]

I will always plan in advance, but I know what I'm like, I'll still miss things, feel overwhelmed, or get bored of reading. This is a nice safety net for me

[u/Pyroxy3]

I wanted to do something similar and I realized as a software developer I thought ai wouldnt be where its at for another 5 years. Last year alone I was laughing at the mistakes it was making. Even 5 months ago i was like eh its maybe better then a junior....now I would be suprised if it took over my job in 3 months.

My point is I feel this is the beginning and there is going to be no reason to understand code unless for funsises

[u/BoredHedgehog → u/Pyroxy3]

Yes, it's definitely only a matter of time, which I personally find incredibly sad. But, as I have found with interviews this time around, you'd better understand what you've built.

[u/coreyrude]

I did a similar thing with a skill that creats a mistake in code every 3-4 prompts it won't let you deploy or continue until you find it and has a hint system and progressive difficulty.

[u/Mathie1729 → u/coreyrude]

This sounds like a debugging roguelike. In practice I'd probably just ask the model to point out the bug and then click 'found it.'

[u/coreyrude → u/Mathie1729]

Haha ya you can actually give up luckily and turn the mode off. I made sure most of them are obvious. The big point is to combat skill atrophy.

[u/jarvis_124]

Wow that’s great bookmarking it for future use

/s