Reducing the cognitive load of AI changes
19 points by amoffat
19 points by amoffat
I like that. I got about halfway there as I have agents contribute to and reference a GLOSSARY.md file but it didn't occur to me to give better names to the items.
Glossary helps a lot, not just with naming, but also code quality, because you have responsibilities of each thing explained.
Having a shared vocabulary of concepts is essential for all programming, in no way limited to AI. (It’s the key feature of Domain Driven Design, for example.) But LLMs tend to invent new confusing names even more freely than humans, and the names tend to be worse! So anything you can do to rein in the naming conventions is helpful. I just use a glossary section of the design overview document.
AIs are kind of a mishmash of every codebase out there. I think their terms are lifted from somewhere far away rather than made up. It's like working with someone who just started at the company. Every day, and their last job was every job.
I guess we can't put 100% of the blame on the LLM…humans came up with "cookies", after all. Somehow it's less charming when the computer does it.
I never in my life heard of "minting" a unique ID until Claude started saying it. (Of course, I am old…no one's ever said "no cap" to me either and I'm pretty sure that's real.)
I vibed a small android app for doing workout tracking. It includes a weight estimator component for figuring out cross lift equivalences. In the process, the AI became much more confident that the estimator and the simulator for it were more accurate than the actual data from my work outs.
I ended up doing a big renaming pass to force it away from using mathematical names for things and to have names that explicitly included "estimate" like "estimated1RM" or "bicepStrengthEstimate".
Too soon to say whether that had the desired effect of reinforcing where truth versus estimate comes from, but I wouldn't be surprised if the math formalisms nudged its weights towards more certainty then it should have had.