Here are some things I am constantly saying to my AI. Or, the things that I frequently ask of Claude…a FAQ of sorts

Routine refactorings

  • Analyze <folder> and look for simplifications, refactorings, or bugfixes
  • Analyze <folder> and look for simplifications, refactorings, bugfixes, improvements or optimizations
  • Analyze <folder> and look for issues and potential remedies
  • Analyze <folder> and look for type strictness improvements
  • Analyze <folder> and look for speed performance optimizations
  • Aggressively refactor <X> (unclear if aggressive as a verb helps but sometimes, that’s what I’m feeling)

After almost every question

  • Are you happy with this solution?
  • Is there anything that would help you gain confidence in this solution?
  • Is there anything else you’d recommend?
  • Is there anything that would make this code more ‘obviously correct’? You can make helper functions or helper react components

Debugging and optimizing

  • Analyze this chrome performance trace file and look for optimizations
  • Please launch puppeteer and do <X,Y,Z> to create a reproducible harness and then look for optimizations
  • You can add debug logging
  • Make sure that the console can see the debug logging of the puppeteer interface

Big refactorings

  • Are there any architectural elements or abstractions that would simplify <folder/system X> at multiple levels?
  • Please analyze <system> and look for vertical optimizations, you can include <vendor code/other subsystems X,Y,Z>
  • Please vendor library X, and aggressively pare it down and simplify it for our needs

Agent-based Documentation

Documentation is a real troublesome area. It often just makes tons and tons of words with unclear value. I try to keep it focused with a couple guardrails

  • Please don’t refer to any specific numbers in the docs, we can’t validate them if they change. Make any values autogenerated
  • Please don’t use any specific code segments in the docs, we can’t typecheck markdown. Make it autogenerated from a file
  • Please make the screenshots in this repo autogenerated using puppeteer https://cmdcolin.github.io/posts/2026-07-31-autogenscreenshots/
  • Please make video demo of the app using autogenerated using puppeteer

Reminding it that big changes are possible

Just after each question:

  • You have broad leverage to make changes. There are no backwards compatibility concerns, so you can change anything you need to
  • You don’t strictly have to take anything as gospel, we have wide leverage to make breaking changes at this stage
  • Don’t be afraid of churn and you can be ambitious

Asking it to grade its own work

  • Critically analyze your above notes and if needed make any additional changes.
  • You can prove it with screenshots if it helps
  • Critically analyze your above findings, which matter most?
  • Critically review your notes. Is this worth doing?
  • Do one more critical analysis of your work
  • Do one more pass and look for further improvements
  • Are you sure about this? Without screenshots proving we made it work I’m not sure we solved it

Delegation

  • These are excellent findings, please launch subagents to implement changes and fixes
  • Analyze the diff between X and Y and launch subagents to double check particular subsystems
  • Analyze the commit messages between local main and origin/main, and launch subagents to code review each change
  • You can launch a Fable subagent to investigate <hard question here that came up in middle of chat with opus for example>

Writing style for docs

  • Reduce prose, cut out unnecessary notes. Let the screenshots speak for themselves
  • Avoid speaking in negative or contrastive framing. Just say what is shown
  • Use simple clear human prose, no telegraphic or staccato sentences
  • Long prose showing step-by-step can be turned into bullet points
  • Keep these docs as simple as possible. Output accessory docs to docs/ folder
  • You can remove em-dashes

My agent-docs directory

I now often have this layout for my repos

  • agent-docs/ARCHITECTURE.md
  • agent-docs/references/ - useful docs that can be cross referenced for any purposes
  • agent-docs/todos/ - basically bugs on issue tracker and small items
  • agent-docs/handoffs/ - when u run outta context, tell agent to make handoff here
  • agent-docs/ideas/ - longer term items
  • agent-docs/architectural-decision-records/ - important decisions, can be re-litigated over time
  • agent-docs/img/ - I use graphviz instead of mermaid because I like the look better, and generate SVG from it

I try to also tell Claude to write out the ‘secret sauce’ decisions from our repo. these can drift over time potentially without care, but it is useful to see it all laid out.

Rules that keep agent-docs from rotting

  • Convert CLAUDE.md preferences into hard rules over time for smaller things. This will start to ‘ossify’ your preferences but can be worthwhile. Add custom eslint rules, etc.
  • Create SYNC comments

Custom statusline

This is my claude statusline. It has rust and node.js fallbacks. It helps me see my context usage, when cache is going to expire, what branch or worktree I’m on, etc.

https://github.com/cmdcolin/dotfiles/tree/main/statusline

Conclusion

I know that it certainly reveals my ‘hand’ so to speak. I hope it perhaps helps though. Knowing small little keywords can really get the agent to key in on a particular mode of operation though. Lemme know in ye olde comments what you think or what techniques you use

Footnote

I was very happy to see that I can now use Fable for many bioinformatics tasks, following their Aug 7 post here https://www.anthropic.com/news/improving-fable-5-s-biology-safeguards