How I use Claude Code to implement new features in an existing complex codebase(sabrina.dev)
sabrina.dev
How I use Claude Code to implement new features in an existing complex codebase
https://www.sabrina.dev/p/ultimate-ai-coding-guide-claude-code
70 comments
I mostly do the same. My workflow is usually like this:
1. Supply CC with a simple user story with light spec / business logic, asking it to write a specification for the feature and ask me any questions that need to be answered to make it complete.
2. Build up the context with all relevant files that I want to use. In Ruby on Rails it means refercing models, views and controllers that show the structure we are going to use.
3. Write the code and tests.
Nice to see!! I wrote a longer post about this: https://open.substack.com/pub/boliv/p/claude-code-usage-patt...
Not sure the complexity of your app but mine's pretty complex with many daily active users. One-shot rarely works unless it's a simple feature/chore and I tell CC exactly what to do, which functions to touch, and how (which defeats the purpose).
A few thoughts on this:
- I wouldn’t outsource my brain to CC when it comes to checking CC’s output. Very mixed results in my experience, and it might discourage further exploration/thinking if you’ve already performed the checklist CC has given you (satisficing).
- Slash commands are the idiomatic way to memoize often used prompts, I wonder why author put them in CLAUDE.md?
- I’m also a bit skeptical that, aside from strict rules CC needs to follow, the encouragements/enchantments for writing good code author put in CLAUDE.md really work. But who knows.
- I DO like the caveats section at the end a lot. This is probably the most important piece of the article, when it comes to large codebases. Never just accept the first draft. Review everything with high suspicion and bend the output to your own style and taste. Otherwise, you‘re pushing legacy code.
- I wouldn’t outsource my brain to CC when it comes to checking CC’s output. Very mixed results in my experience, and it might discourage further exploration/thinking if you’ve already performed the checklist CC has given you (satisficing).
- Slash commands are the idiomatic way to memoize often used prompts, I wonder why author put them in CLAUDE.md?
- I’m also a bit skeptical that, aside from strict rules CC needs to follow, the encouragements/enchantments for writing good code author put in CLAUDE.md really work. But who knows.
- I DO like the caveats section at the end a lot. This is probably the most important piece of the article, when it comes to large codebases. Never just accept the first draft. Review everything with high suspicion and bend the output to your own style and taste. Otherwise, you‘re pushing legacy code.
[deleted]
I agree with the notion here that things are moving so fast that most blog posts will be outdated quickly.
However posts like this is valuable for new people to get a basic understanding of how these tools could be used in a very simple, beginner friendly, setup.
However posts like this is valuable for new people to get a basic understanding of how these tools could be used in a very simple, beginner friendly, setup.
This is equivalent of .vimrc file. ".clauderc" .
It will be interesting to see how all this works out when the honeymoon phase is over.
At the moment they burn a investor money to gain customers by giving us free tools and cheap LLMs.
That will end at some point.
At the moment they burn a investor money to gain customers by giving us free tools and cheap LLMs.
That will end at some point.
One perspective could be that this is a moment to leverage. Subsidized LLMs won't be around forever, so this is a great time to build something that you wouldn't have had the time to build otherwise.
The author describes a lot of directives they found useful. Be aware Claude has the concept of `slash commands` https://docs.anthropic.com/en/docs/claude-code/slash-command...
I stumbled upon the author’s command `qnew` to read Claude.md.
Why would you need that?
> CLAUDE.md is a special file that Claude automatically pulls into context when starting a conversation.
https://www.anthropic.com/engineering/claude-code-best-pract...
Why would you need that?
> CLAUDE.md is a special file that Claude automatically pulls into context when starting a conversation.
https://www.anthropic.com/engineering/claude-code-best-pract...
That confused me as well. The whole point of CLAUDE.md is that it is automatically injected into the rolling context of any Claude interaction/thread.
That CLAUDE.md file that they've posted is also HUGE - Anthropic themselves recommend keeping it on the more concise side. If you need more, consider just creating dedicated subagents for "UI/UX reviewer", "search", etc.
That CLAUDE.md file that they've posted is also HUGE - Anthropic themselves recommend keeping it on the more concise side. If you need more, consider just creating dedicated subagents for "UI/UX reviewer", "search", etc.
My CLAUDE.md has references to other documentation
Like "for guidance on Go library selection refer to docs/go.md"
That way the main file stays compact.
Like "for guidance on Go library selection refer to docs/go.md"
That way the main file stays compact.
subagents were not yet released at the time of my blog post
That many sites about AI look a lot like scam sites ("make money fast") is a real turn-off -> https://www.sabrina.dev
Maybe it does have some valuable content but I will just close it.
Maybe it does have some valuable content but I will just close it.
I agree. I remember a year ago some a submission on this forum by Sabrina where she was evaluating LLMs on SAT math problems. The post was called like “ChatGPT-4o vs. Math”. I thought it was pretty insightful, but now that post is deleted from her blog and it seems like the blog as a whole is leaning into attracting people who are nontechnical and want to use it to generate social media content. Weird vibe in the comments of her posts and videos too.
I migrated from beehiiv to substack a few months ago but haven't migrated some of my older posts
Wow, geez. That is terrible, I'm surprised a website like that can have any actual content as TFA
The grifters have entered the arena.
Hype is like catnip for them. They've been around for a while, many of the OG AI YouTubers didn't know anything about it when they started to pretend to educate.
I mean, the grifters have started it. They grifted for way too much money without ANY plan on how to actually get money back to the investors. Including the dubious benefits, just promising a "quick fix".
That is a bit over the top, but the core statement kind of stands.
That is a bit over the top, but the core statement kind of stands.
I'm the writer of the blog post. I don't sell ai courses, consulting, coaching, or anything like that. But I do use claude code to help me build my SaaS app as a bootstrapped solopreneur. I also sold an AI startup in early 2021, which I founded back in 2014 when the hyped term was "Big Data". I've been around a few hype cycles now..
[flagged]
Can you please not gut your comments by deleting the content, once they have replies?
It destroys the context for readers, making the thread worse for everyone.
It destroys the context for readers, making the thread worse for everyone.
That’s fair, I shared things that weren’t in a state to communicate. I shouldn’t have commented at all.
Appreciated! And yes, that happens sometimes.
Actually please write an article about how you are currently using it then. I've been actively using it and working with sub-agents. I feel like there are very little resources out there on more complex Claude Code setups.
I would love to see other setups, like what MCP, hooks, sub-agents, commands, etc.
I would love to see other setups, like what MCP, hooks, sub-agents, commands, etc.
.
Wow, that is a huge instruction set.
I've created a (way smaller) "/hire" command that does something similar, but I should probably turn it into an agent as well, as the commao is only creating agents, and I still need to do further adaptation with individual promoting and edits
It's these little, but crucial insights that make all the difference, so thank you!
I have the exact same feeling about losing time, for me it's starting to turn into an addiction,
I'm buiding a new side product, and the sense of urgency combined with the available capability makes it hard for me to stop working.
Progress is going so fast that it feels like the competition might catch up any time now.
I now restrained myself upfront with predefined timing windows for work, so the I manage to keep my sanity & social life from disappearing...
"What a great time to be alive"
I've created a (way smaller) "/hire" command that does something similar, but I should probably turn it into an agent as well, as the commao is only creating agents, and I still need to do further adaptation with individual promoting and edits
It's these little, but crucial insights that make all the difference, so thank you!
I have the exact same feeling about losing time, for me it's starting to turn into an addiction,
I'm buiding a new side product, and the sense of urgency combined with the available capability makes it hard for me to stop working.
Progress is going so fast that it feels like the competition might catch up any time now.
I now restrained myself upfront with predefined timing windows for work, so the I manage to keep my sanity & social life from disappearing...
"What a great time to be alive"
[deleted]
The situation is of your own making. You can change/get out any time.
>Apologies, I'm not an article writer. I focus all my time on improving my own setup.
Maybe that's why the guides you see appear a bit out of date? Writing, all kinds of communicating, takes time, both in organizing and compiling your thoughts
Maybe that's why the guides you see appear a bit out of date? Writing, all kinds of communicating, takes time, both in organizing and compiling your thoughts
[deleted]
We’ve been building in this direction for a bit over a year now. I don’t see your contact info but please reach out over email if you’re interested in checking out our approach and maybe working with us!
.
It’s not the specific agent config or anything like that I’m after, just the genuine interest+enthusiasm in an area we’re actively working on. The central premise to what we’re building is our system for reusable and composable AI workflows.
Shit’s moving fast and the math works out such that it’s probably better to just find someone at the bleeding edge and offer to pay them really generously to work with us than to recruit for this work normally. If you change your mind you can find my email on my profile!
Edit for more context: We’ve basically had the same thing as Claude’s slash commands (we call them workflows) since November, but then we switched gears and made our cloud IDE/agent sandbox and other components of our infrastructure layer the top priority.
That’s working and the timing is amazing since we should be able to just glue all these new cli (sub) agents in between our workflows and agent infrastructure. I suspect someone who understands terminal agents well could do it about 4x faster than me.
Shit’s moving fast and the math works out such that it’s probably better to just find someone at the bleeding edge and offer to pay them really generously to work with us than to recruit for this work normally. If you change your mind you can find my email on my profile!
Edit for more context: We’ve basically had the same thing as Claude’s slash commands (we call them workflows) since November, but then we switched gears and made our cloud IDE/agent sandbox and other components of our infrastructure layer the top priority.
That’s working and the timing is amazing since we should be able to just glue all these new cli (sub) agents in between our workflows and agent infrastructure. I suspect someone who understands terminal agents well could do it about 4x faster than me.
I think the basic issue for me is that people put this stuff out as if it's some big discovery, and yet my own usage is way different and serves me just fine thank you. These have the feel of a developer who has just discovered development and then want to tell you about all the best tools. But it's not really about showing you the best tools, is it? Rather, it's about riding the hype train and creating slop for more eyeballs.
Respectfully, I think you are being reflexively contrarian or overindexing on the vibe coding hype train. The way vibe coding UX works is basically just having LLMs guess what they need to do to complete a task and then sending it off to do it and try to fix anything that doesn't go according to plan along the way. Nothing big there.
I had started working on an AI devtool product a few months before Cursor took off, I didn't even know about them when I first started, and I hated that such a dumb UX was setting the narrative in this space. LLMs had essentially no ability to decompose and plan tasks at the time, and they weren't fucking sandboxing it!
Terminal agents are actually moving towards the UX I've been building/anticipating for. In March of 2024 I was playing around with GPT4 and saw it oneshot a microservice I asked it to make. I was so excited about the implications of where this stuff could go that I quit my job at google just to start building in this space.
Without getting into all the details, I am pretty convinced there must be some particular way of arranging infrastructure primitives and AI-coding tools in a way that properly decomposes and executes arbitrarily large or complicated tasks (limited only by available time and resources). Claude code is IMO getting closer to that by the week. No iterative change is crazy science or anything but there are some genuinely novel and exciting patterns for computing things underway.
I had started working on an AI devtool product a few months before Cursor took off, I didn't even know about them when I first started, and I hated that such a dumb UX was setting the narrative in this space. LLMs had essentially no ability to decompose and plan tasks at the time, and they weren't fucking sandboxing it!
Terminal agents are actually moving towards the UX I've been building/anticipating for. In March of 2024 I was playing around with GPT4 and saw it oneshot a microservice I asked it to make. I was so excited about the implications of where this stuff could go that I quit my job at google just to start building in this space.
Without getting into all the details, I am pretty convinced there must be some particular way of arranging infrastructure primitives and AI-coding tools in a way that properly decomposes and executes arbitrarily large or complicated tasks (limited only by available time and resources). Claude code is IMO getting closer to that by the week. No iterative change is crazy science or anything but there are some genuinely novel and exciting patterns for computing things underway.
When someone has a YouTube channel about programming with a certain level of polish they are not trying to be a professional programmer, they are trying to be a professional YouTuber.
[deleted]
It's from July 6, so yeah a month in the past is totally right.
She has newer posts on sub agents
She has newer posts on sub agents
[deleted]
to be fair, the linked youtube video from the article is literally 4 weeks old, so "at least a month in the past" is probably exactly accurate if you are moving at the same pace as the author.
[deleted]
> If you don't discuss hooks and subagents, i'm not sure what you're doing right now.
Agents have their own context and can be useful for tasks that can be parallelized, which is a minority of tasks. How are they critical to better performance for you?
Agents have their own context and can be useful for tasks that can be parallelized, which is a minority of tasks. How are they critical to better performance for you?
This is the best question anyone has asked.
Let's consider context. At some level the more context you have is good. At some level, the more irrelevant context you have is bad.
Okay. We have at top level of context, a hook that forces a system prompt on every action.
Next level we have a ./claude/CLAUDE.md then we have the project level CLAUDE.md then we have a possible not required agent setup then we have the instructions you give it
We know that CLAUDE.md gets lost in the context, at any level. The system prompt level hooks don't.
Why does the CLAUDE.md get lost? Why are we losing ability with a longer context.
The problem is irrelevant context to the action. The Documentation agent doesn't require the Golang modernization rules. The Golang agent, doesn't require the planing coordinator rules.
So the question I asked myself last weekend was, what is the experience if you split the contexts to only the required information for the task.
I did head to head battles with agents, reading in the information, versus contextual specific information. The agents with context specific destroyed the competition. Like it was another world.
So then I ran head to head tests on the type of information. Etc etc. My current setup is the best level achieved in those tests.
So my argument is that removing the context that is entirely irrelevant for the agent improves performance dramatically.
But I'm one person doing tests... it's true for me. Maybe it's not true for others. People have to explore the conception and determine that.
I can only tell you what has worked best for me, and for me, it's like a model jump in performance improvements.
Let's consider context. At some level the more context you have is good. At some level, the more irrelevant context you have is bad.
Okay. We have at top level of context, a hook that forces a system prompt on every action.
Next level we have a ./claude/CLAUDE.md then we have the project level CLAUDE.md then we have a possible not required agent setup then we have the instructions you give it
We know that CLAUDE.md gets lost in the context, at any level. The system prompt level hooks don't.
Why does the CLAUDE.md get lost? Why are we losing ability with a longer context.
The problem is irrelevant context to the action. The Documentation agent doesn't require the Golang modernization rules. The Golang agent, doesn't require the planing coordinator rules.
So the question I asked myself last weekend was, what is the experience if you split the contexts to only the required information for the task.
I did head to head battles with agents, reading in the information, versus contextual specific information. The agents with context specific destroyed the competition. Like it was another world.
So then I ran head to head tests on the type of information. Etc etc. My current setup is the best level achieved in those tests.
So my argument is that removing the context that is entirely irrelevant for the agent improves performance dramatically.
But I'm one person doing tests... it's true for me. Maybe it's not true for others. People have to explore the conception and determine that.
I can only tell you what has worked best for me, and for me, it's like a model jump in performance improvements.
It's been my experience too, already prior to support for sub-tasks/agents.
I've been exploring the ways in which I could "lazy load" context depending on the task at hand. I've approached this by defining an AI "receptionist", a set of roles and a set of tasks.
The receptionist is the entrypoint of the system. It knows where to find roles/tasks but only loads very basic information about the roles.
Depending on the role I ask for, it then loads the right role file, which in turn loads additional context. Then I ask for whatever i want to do, and it loads specific task files based on what I asked. And the task files load additional context etc.
This works quite well because I end up with just the right context for the task at hand. And each role/task can actually be executed as a sub-task/agent
I've been exploring the ways in which I could "lazy load" context depending on the task at hand. I've approached this by defining an AI "receptionist", a set of roles and a set of tasks.
The receptionist is the entrypoint of the system. It knows where to find roles/tasks but only loads very basic information about the roles.
Depending on the role I ask for, it then loads the right role file, which in turn loads additional context. Then I ask for whatever i want to do, and it loads specific task files based on what I asked. And the task files load additional context etc.
This works quite well because I end up with just the right context for the task at hand. And each role/task can actually be executed as a sub-task/agent
You stumbled on to the solution before the tools caught up to you. really cool.
> So my argument is that removing the context that is entirely irrelevant for the agent improves performance dramatically.
100% agree on building the optimal context, just have not seen parallel agents do better at sequential tasks. the documentation agent may have better initial context about how to write documentation, but it doesn't have the context of the changes, apart from what is passed to it / can explore. if we don't spawn a new session, and instead throw it a /document command - that would still get all the guidelines and rules for writing documentation, and it should have the same weight since it's at the bottom of the context.
for me the highest 'model jump level' performance booster is externalizing context and controlling the process - having claude initialize a plan file with a pre-defined template that makes it use that as its to do list and documentation place, and getting it to use that as its primary working area
100% agree on building the optimal context, just have not seen parallel agents do better at sequential tasks. the documentation agent may have better initial context about how to write documentation, but it doesn't have the context of the changes, apart from what is passed to it / can explore. if we don't spawn a new session, and instead throw it a /document command - that would still get all the guidelines and rules for writing documentation, and it should have the same weight since it's at the bottom of the context.
for me the highest 'model jump level' performance booster is externalizing context and controlling the process - having claude initialize a plan file with a pre-defined template that makes it use that as its to do list and documentation place, and getting it to use that as its primary working area
I am doing that too. Perhaps I am misjudging which part is providing which benefit, but when using the plan system as well as the agent, the agents with this context setup perform much better.
It all builds on each other, so it can be slightly challenging to untangle which part is providing the majority of benefits.
It all builds on each other, so it can be slightly challenging to untangle which part is providing the majority of benefits.
What are hooks and subagents then?
Why did you replace your comments in this thread with . ?
Because I gave examples, and details, and thousands of people read them from a pastebin i used to share.
I didn't release it as open source or anything, just sharing. I don't want to take questions concerning it so I can focus on moving it forward.
Today's goal is to try to build self healing agents that automatically fix the problems they encounter so they only happen once, automating a manual process I successfully use.
Perhaps if that works out well, that is something releasable I can do in a real way as opposed to paste bin.
I didn't release it as open source or anything, just sharing. I don't want to take questions concerning it so I can focus on moving it forward.
Today's goal is to try to build self healing agents that automatically fix the problems they encounter so they only happen once, automating a manual process I successfully use.
Perhaps if that works out well, that is something releasable I can do in a real way as opposed to paste bin.
I'm the original blog post writer. Sadly I have no idea the context for this comment thread now.
Sadly I was just late to the discussion and missed the stuff. Would you mind sending what you shared to an email of mine? Not requesting further communication, just simply curious what people do with and around this.
Genuinely, how do you keep up to date with these features while still being focused at the task?
The more I focus the less I have time to read and experiment O want to finish it. What are your sources and how are you balancing it ?
The more I focus the less I have time to read and experiment O want to finish it. What are your sources and how are you balancing it ?
Honestly, the release of sub-agents was the first time it felt actually meaningful.
MCP servers and the rest have not provided the type of gains sub-agents have. Hooks and subagents actually provide tangible value. Enough that it's changed my structure entirely to be tool focused, and not output focused.
MCP servers and the rest have not provided the type of gains sub-agents have. Hooks and subagents actually provide tangible value. Enough that it's changed my structure entirely to be tool focused, and not output focused.
This is like 99% of my CC interactions working on top of a well structured codebase and it just works perfectly for almost any task I throw at it.