COOL AI THING #30 / WORKSPACE INSTRUCTIONS
One brief.
Two instruction files.
I work with more than one AI coding tool. I wanted one place to write how I work, then a repeatable way to give each tool the right instructions.
A good brief should not
need rewriting for every tool.
A workspace instruction file tells an AI coding assistant how to work in a project: what the source of truth is, which boundaries matter, and how to check its work. Those instructions are more useful when they stay current.
I use Claude and Codex. Copying the same guidance into their separate files gave me two places to update and two chances to let them drift apart.
Write once.
Generate deliberately.
My shared instructions live in LLM.md. A Python command reads that source, a rule ledger, tool-specific fragments, and base files. It validates the pieces, then renders the generated sections of CLAUDE.md and AGENTS.md.
The command preserves handwritten content outside its marked generated section. A check mode catches direct edits inside generated content; intentional regeneration uses an explicit apply mode. The tool is deterministic Python. It does not ask a model to rewrite the rules.
The project Claude file intentionally does not repeat a shared block already supplied by the global Claude adapter. The exact generated target matters when showing a sentence in both outputs.
The generator exists.
The film is still being made.
The adapter generator is tracked in my workspace, and its public repository uses invented sample instructions so its behavior can be checked without publishing my private working policy.
The comic paper and ink on this page explain the idea. They are illustrations. A genuine command capture and the finished Cool AI Thing #30 video are still production work, so this page does not present either as complete.
Video and final demonstration capture are pending review. The generator source is available below.
From the canvas
to the actual files.
The planned video begins with my painting, moves into a comic-style explanation of workspace instructions, and unfolds LLM.md into the tool files. Its final demonstration needs to show real generated output. I’ll add the finished video here after the complete cut is reviewed and published.
Read the generator.
Try a safe example.
The public repository contains the generator script with synthetic inputs. My working instructions remain private. The README shows how to render sample CLAUDE.md and AGENTS.md files and describes a current limitation of its output comparison flag.
The repository currently has no open-source license; public visibility alone does not grant reuse rights.