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.

The workspace also has branch protections to prevent us from commiting our workspace to main, or from clearing our workspace bringing in new updates from the main branch. Archives however always succesfully commit to the main branch allowing the sharing functionality.

Slash Commands

Every workspace needs a control panel, and (slash) commands are it. In your local .claude directory, placed under the 'workspace' name-space, a comprehensive suite of commands enable the intelligent management of your workspace.

Core Commands

• /new-workspace - starting from a clean main branch, creates a new branch with intelligent naming, copying over a fresh workspace. Provides your CLAUDE.md with a branch purpose statement and other metadata. safety check built in.
• /archive-workspace - Snapshot your whole workspace directory into an intelligently named folder in branches/, preserving and making available the context for the lifetime of your project. This command can be run at anytime, even before finishing your work, and the archive will be intelligently updated.
• /merge-preflight & /merge-branch - These command are used in unison to firstly check and prepare the branch for merging, preflight can be progressively re-used until you get the greenlight to merge. merge-branch then gets down to business merging your branch back to main (completing your work), then cleaning up the branch as per your instructions.
• /discover & /research - Two key context building commands, instructing Claude to use the native Task() agents to comprehensively search either the codebase (discover) or the web (research) for context. Fill in the relevant prompt template (eg prompts/discover.md) and @ inject as a command argument.

Additional Commands

• /context-files - Builds a file list for easy guiding of claude based upon any discovery or plans created in workspace.
• /rename-history - Renames a chat transcript if the file was not autonamed by the session_end hook.
• /prune-history - Suggests redundant chat transcripts to remove from history if lots of small logistics based chats have been recorded.
• /tree - Backup command to run the tree tool. hard coded directory paths, change as required. builds a full view of the codebase directory paths entered and outputs a tree file.

Hooks

The workspace's crown jewel is a suite of premium hooks, leveraging an excellent ruby library called "claude_hooks". The library does all the background work of managing hooks with Claude Code. It uses a single point of entry for each hook event, intelligently combines multiple hooks and outputs all the correct codes and json for claude to respond to. It also comprehensively logs our hooks actions.

The workspace uses the three main hook events applicable for context management: session_start, session_end & user_prompt_submit. The workspace hooks shape the conversations we have with Claude like nothing else. They are a joy to use, Claude responds really well to these.

• session_start - Runs the tree tool to build up to date, directory and file context for claude. Injects workspace context (including tree) into the session before conversation or coding begins.
• session_end - Extracts the session transcript from the .claude folder and saves it to the history folder. Also renames and summarises the transcript using a headless claude session.
• user_prompt_submit - Runs a suite of word based triggers that manipulate Claude's output allow for advanced context building in the session.

These hooks are all written in ruby, if you don't want to use ruby claude may be able to help you build these hooks in python / typescript etc but you will lose access to the awesome "claude_hooks" library. meaning they may not work quite as well.

The claude_hooks library also produces a customisable log record for each session, allowing for advance diagnostics and checking of each hook event. These are captured in the users (global) .claude directory.

A config file is available for 'claude_hooks' to allow customisation of some hook parameters, like; what directories the tree command searches, or the files to use for preloaded context.

What makes this special ?

Although we may have been through a few of these already, here is a list of workspace features with some guidance on how to I use them. Most of these will be very unique and innovative in the Claude Code workflow space. try them yourself and see.

Conversation Capture

This is a premium context capture tool. Every conversation you have with claude can be parsed and recorded in your workspace. Allowing you to re-read, include in other sessions or iterate over for patterns. The session_end hook captures this using some special functionality...

• Every historical conversation capture file is built using template files. These are all configurable with both the plain text formatting and the erb (ruby-based interpolation) code. These templates produce a rich and readable history file, with greatly reduced token load. So they are quite efficient to use as a context source.
• Relies upon the inbuilt /exit or /clear commands to trigger the hook. Capturing meaningless or logistics chats can be prevented by just closing the chat window. If you need to capture a chat that was closed accidentally, just use /resume to reload it.
• Filters out useless transcripts that claude code produces so that only the key discussions are captured.
• Waits to exit the chat until the hook finishes or happens in the background when clearing the chat.
• A headless session is created when exiting or clearing that analyses the transcript and renames and summarises the file after the hook creates the file.

This results in some really great conversation history files, featuring...

• The transcript file metadata so that the history file can be intelligently updated if the hook fires a second time.
• Rich content signalling; when new conversation branching arise (when the user resumes or rewinds a conversation), The thinking level that was used for a user turn, who's turn in the conversation, slash commands the user used.
• Captures all the read, write, edit, bash, agent and skill tool usages, recording the specific tool used and the file or command utilised, but leaves out the file or command contents. This is a huge token saver but preserves the flow allowing understanding of what happened with these files and commands.
• The headless call produces an excellent contextual file name with date prefix so that you can easily get an overview without opening the file. It also produces a summary so that claude can contextually search history files for specific topics.

A great workflow I have using this feature, is... Open up a conversation with claude, chat about the changes I want to make, have claude search and discover naturally, then when finished exit the conversation. Then I start a new conversation, load the captured transcript and get to work with advanced, token-saving, naturally built chat context.

Here is an extract of a history file.

Session: f34c642d-3573-4bf1-9af0-e1e431df9aba
Date: 2025-12-03 18:18
Branch: docs/extract-rails-patterns
CWD: ~/Projects/37signals/fizzy

============================================================
[SUMMARY]
>>>
Explored Fizzy's layout system and content injection patterns. Discovered minimal shell layout with named yield slots and instance variable configuration, CSS-driven container widths via `.panel` classes and `:has()` selectors, and zero-JS user-scoped CSS. Extracted findings into layout-shell.md pattern documentation.
<<<
------------------------------------------------------------
[✨ NEW CONVERSATION BRANCH]
[USER]    💭: none
as per our @CLAUDE.md, lets discuss how fizzy uses application.html and subsequent patterns to inject content and partials, particularly interesting is "content_for" on most view pages.

------------------------------------------------------------

[ASSISTANT]
Great topic! Let me explore how Fizzy uses `content_for` and the layout patterns.

------------------------------------------------------------

[READ TOOL]
File: ~/Projects/37signals/fizzy/app/views/layouts/application.html.erb

------------------------------------------------------------

[ASSISTANT]
Interesting patterns emerging. Let me look at the shared head partial and a few representative views to see the full picture:

------------------------------------------------------------

[READ TOOL]
File: ~/Projects/37signals/fizzy/app/views/layouts/shared/_head.html.erb

------------------------------------------------------------

Session Context Injection

Context injection when the session starts, is a powerful tool, enabled by the session_start hook. Claude silently receives (not shown to the user) very relevant and helpful context from the workspace before coding or conversation begins. This session_start hook uses some advanced functionality to deliver context to claude...

• Creates a tree.md file that shows the project's directories (based on config.json) and files in a tree structure. This is the most token-efficient way to show claude all the relevant files and folders in your project.
• Stitches together configurable (multiple) context sources with start, end and separator formatting. This context is then shown silently to claude when the session starts.
• Logs the injected context in the (global) .claude directory for reference purposes if you need to check what claude is actually seeing.
• Stays in context for the whole session in a background system instructions section in Claude's system prompt.

This produces premium usable context before the session begins...

• tree.md allows claude to instantly jump to any file or folder or see the whole project structure. NO MORE SEARCHING your codebase. File and folder names and nesting reveal to claude a lot of logic and flow. This becomes like a super power for claude.
• Any file can be included in the pre loaded context using the config.json file. The two other defaults are the CLAUDE.md and WORKSPACE.md files.
• The CLAUDE.md file gives claude an understanding of the current workspace purpose and any branch relevant discoveries that need remembering, this stops the bloating of the project level claude.md file and allows for surgical memories (eg switch branches --> switch relevant memories).
• The WORKSPACE.md file guides claude on the logistical requirements of the branch. One branch might be a multiphase feature, another might be a quick fix. Through this file, Claude now knows this and other important requirements (like attached git issues, merge ).
• The injected context is silent, so it doesn't clog up the chat, it doesn't appear in any history files either. However, a system message is inlined in the chat, so that you can confirm context has been added.

tree.md example that is shown to Claude

├── dev
│ ├── branches
│ └── workspace
│ ├── context
│ │ └── tree.md
│ ├── research
│ ├── reviews
│ ├── tasks
│ │ └── assistant
│ ├── CLAUDE.md
│ ├── README.md
│ └── WORKSPACE.md

User_prompt_submit Triggers

Back when sonnet 3.5 was the "world's greatest coding model", I invented an advanced context shaping system using styles. Each style would produce a specific structured output that would significantly improve the quality of the context.

Here is my reddit post about it that was pinned by the mods... https://www.reddit.com/r/ClaudeAI/comments/1i4c6jx/my_guide_to_using_styles_effectively

So over a year later, these "styles" can still be used per turn in claude code just as effectively, but it is now way easier using a user_prompt_submit hook. Simply use a trigger statement and bam! Claude's output is instantly different...

• Uses unique trigger statements directly in the user's prompt to shape Claude's next response. Thoughtfully, they should not trigger during general conversation.
• Each trigger-injected style or output uses a template file. These can be edited without touching the hook's code files, allowing you to iterate the "style" if needed.
• More triggers can be easily added by copying the existing hook files and logic. The only changes required are the naming, the trigger statements and the output template. A slight adjustment of the log and system message output can also be made.
• Logs the hook in the users (global) .Claude directory and shows a system message to the user in the chat to indicate that a trigger fired.

Here are some of the triggers and styles produced...

• Show working - Is still my all time favorite. Claude reflects back his understanding of your task, all his ideas for completing the task, any issues he might come across and where in the project he expects the changes to happen and what format it will take. This is gold for catching any misunderstandings, adjusting any task parameters before starting, addressing issues etc. It also is the best prompt improver ever, as claude has just restated your initial prompt but usually improved it A LOT. This is then snapshot into the chat stream so that he works from the improved prompt, not your crappy mind dump.
• Claude Space - An alternative to "thinking" which claude does on a turn-by-turn basis, except this is "session" thinking. As effective as thinking for improving context, claude is given a "space" to think out loud about the WHOLE conversation so far. He becomes really candid and produces thoughts applicable to the chat that would never normally be surfaced. Once again, this is then permanently on record in the chat for further discussion or reference.
• Show options - Gets claude thinking about different options for completing the task. This then produces output that wouldn't normally surface, whereby he is asked to either recommend a new option, stay with original or cherry-pick to combine.
• Show strategy - Much like show working, forces claude to reveal HOW (his process, not his changes) he is going to complete the task. provide other strategy options and reveal any difficulties he may encounter. This enables user intervention and leaves a strategy record in the chat that claude will now follow more vigorously. Trigger this one during planning after he has a decent idea of what the task involves.
• Show context - Pop this to get claude to inject all the places he intends on finding context for his task. This get him thinking about WHERE to find context far more effectively. Also intervention and guidance opportunities arise.
• Show difficulties - Claude analyses the chat and reveals if he and the user are having any communication difficulties. If any, the chat will be left with a record of the difficulties, making it far more likely for him to stop "misbehaving". Also his reply can be added to CLAUDE.md if significant enough to provide the guard rail on a broader scope.

These can produce conversations rich in shaped context without pre placing guard and guide rails everywhere (output-styles, CLAUDE.md, commands etc).

Just a simple warning. Use only one trigger statement per turn, claude will get confused otherwise.

Branches Archive

Once your branch is finished. Very simple automation can archive all the workspace context into a separate auto-named dev/branch/{name} directory. This creates an amazing record and history over time of how you built your project. Each branch archive containing all the relevant workspace context and files produced while on that branch.

Branch archiving also allows you to work on multiple branches at once using only branch relevant context, all the other branch's workspace context isn't getting in the way for claude to stumble over. If you need to use some workspace context or code snippets on another branch, archive it early (you can overwrite it later) then access that context through the branch archive.

An even bigger level up is A/B building features in parallel. Create a branch for vibe code and another branch for step by step guided development for the same feature. merge the winner, cherry-pick between them using the archived filebox directory.

Blank Slate

Finally, this workspace system is not a workflow. It is a toolset, infinitely able to accommodate any Claude Code workflow. Use what you want, leave out what you don't, customise what gets shown to Claude.

This workspace deliberately avoids implementing any skills, agents, output-styles, mcp servers, CLAUDE.md these are all up to you. But it also doesn't really need those tools either to be effective. Everybody loves efficient token usage and preserving usage limits all session and week, while providing key usable context right???

What dev workspace will do is enhance and enable your workflow to operate much better, probably even enabling trimming your workflow down as the workspace tools provide a lot of the core context. You will also have a place to store all the files and planning that your workflow creates, but it will be clean and organised.

For teams the complete visibility into branch context generated by an individual, the ability to share context between developers through archived workspaces on main, solid templates that can be reliable across the whole team, but also customisable per workspace, integrating with individual developers custom workflows, will be not yet be experienced by most teams.

Don't be surprised if your velocity increases. Claude's quality greatly increases. Re-usable context accumlates, but stays out of your way, Teams thrive from the simple but powerful implementation. Enjoy for free, feedback welcome.

Instructions

See the workspace README.MD for installation and references.