Dev Workspace
What is it?
This is a developer workspace system for use with Claude Code. The premise is simple... Shape, store, build and reveal context generated by and used for Claude AI while working on a codebase.
This workspace system is not intended to replace any of your existing workflows and allows for integration of any new workflows you may want to create or try yourself. This system doesn't touch: CLAUDE.md, agents, skills or mcp servers, you are free to use these tools as you wish.
A workspace has its foundation in only 4 pillars. Git, Hooks, Slash commands and Directory / File templates. This simple combination of tools, produces a very powerful outcome that significantly enhances your and your team's ability to generate high quality work.
The 4 Pillars
Directory System
The foundation of this system is your context storage location and templates. This is where we streamline everything with intelligent and consistent directories for all the context you shape and build, it is precious, it must be stored well. Not just for you but for Claude as well.
This is the anatomy...
└── dev
└── workspace
├── context
├── filebox
├── history
├── plans
├── prompts
├── research
├── reviews
└── tasks
├── CLAUDE.md
└── WORKSPACE.md
Each of these provide Claude and yourself with all the context storage you need. These are the directories and files...
- context/ - A place for command generated discovery context, tree views etc. Gives claude vision over your codebase so he doesn't have to go digging all the time.
- filebox/ - A place for all your scratch files, a file dump location. So important when claude is pumping out all kinds of random stuff.
- history/ - All your conversations with claude, neatly presented, summarised and named. Ready to be re-used or perused.
- plans/ - All the plans you create with claude can go in here. Has prebuilt product and architecture templates to build out.
- prompts/ - Copy and pasting prompts into chat has never stopped being useful. Building your prompts in txt files before pasting, takes the pressure off and allows for more fidelity in the prompt. Comes with some prebuilt templates for highly structured discovery and research. Also has some xml i was experimenting with (opus is good enough now to not really need these).
- research/ - Comes empty but allow for the structured research command to have an output location, can also be used for any other adhoc research you bring to the table.
- reviews/ - Also empty, but a few of the workspace's commands will end up with some reviews in there.
- tasks/ - For both claude and you to create referenceable tasks lists. Often coming from the end of your planning workflow. allowing you to track work over many sessions.
- CLAUDE.md - Comes preconfigured with useful context regarding the workspace system. Is designed to be shown to claude, when the session starts. Has a section to quickly place useful discoveries applicable to the branch only.
- WORKSPACE.md - Has some preconfigured markdown checkboxes that guides Claude when managing the workspace. Designed to be shown to Claude when the session starts.
Git Management
Every fix, feature, bug, refactor, documentation build, becomes a git branch in your project repo. Like magic, this new branch also gives us a brand new, clean "workspace" to work in, with empty folders and ready to use templates. Every time we start new work we get a brand new clean slate. This feeling is truly awesome.
We can work on different branches concurrently and each branch's unique context is right there at our fingertips in the same place as always. Changing branches, changes context. This makes our context very targeted and focused, which Claude responds to excellently.
As you go you commit all changes to the feature branch. Once complete Claude checks a specific WORKSPACE.md configuration file to know exactly how to merge your branch and what to do with all your workspace context. Your branch is then automatically prepared, safety checked, then merged back to main. Once in the flow, branches can come and go freely. "but what about all that precious context we have built up on the branch?" Once again we experience the magic...
We also have the tools to archive our workspace and keep the archive updated as work progresses. In dev/branches/ a new archive directory is spawned, containing every piece of context we have created thus far on the branch. What does this do? Well, we can access other workspaces (branches) context or share snippets and files, through the archived branch. Or, re-visit the context, build processes and conversations with Claude specific to that branch.
So workspaces are brand new for each time you start new work, but archives persist and are shared with the whole project. This feels like magic when experienced in full.
