▲ 534 points
back
188 comments
> Finally, we keep this file synced with an AGENTS.md file to maintain compatibility with other AI IDEs that our engineers might be using.
I researched this the other day, the recommended (by Anthropic) way to do this is to have a CLAUDE.md with a single line in it:
@AGENTS.md
This is one thing I think they need to get in-line with, and rename CLAUDE.md to AGENTS.md to follow convention.
We have an AGENTS.md symlinked to CLAUDE.md, seems to work fine.
Yeah that's probably a slightly cleaner way of doing it.
You think it would be a good idea to use a symlink instead?
In my experience, neither Claude nor any other agent actually reads AGENTS.md (or CLAUDE.md or anything else) without being told to explicitly every session.
I really like this take on MCP: https://blog.sshh.io/i/177742847/mcp-model-context-protocol
> Instead of a bloated API, an MCP should be a simple, secure gateway that provides a few powerful, high-level tools [...] In this model, MCP’s job isn’t to abstract reality for the agent; its job is to manage the auth, networking, and security boundaries and then get out of the way.
Thanks! I def don't think I would have guessed this use case when MCP first came out, but more and more it seems Claude just yearns for scripting on data rather than a bunch of "tools". My/MCPs job has become just getting it that data.
This is how MCP works if you use it for as essential an internal tool API gateway (stateless http) instead of a client facing service that end users are connecting directly to. It's basically just OpenAPI but slightly more tuned for LLM inference.
Agreed. My only MCP is a code interpreter. I also recently started experimenting with making an MCP “proxy” which acts a better harness that lets the agent call MCP from within a code interpreter [1]
But in general I still don’t really use MCP. Agents are just so good at solving problems themselves. I wish MCP would mostly focus at the auth part instead of the tool part. Getting an agent access to an API with credentials usually gives them enough power to solve problems on their own.
[1]: https://x.com/mitsuhiko/status/1984756813850374578?s=46
At this point these tools are all pretty good. I also feel like folks often also over index on the output style or UI. Like to me the “you’re absolutely right!” sycophancy isn’t a notable bug; it’s a signal that you’re too in-the-loop. Generally my goal is to “shoot and forget”—to delegate, set the context, and let it work. Judging the tool by the final PR and not how it gets there.
You're going to immediately be overwhelmed with code, comments, markdown files, and all manner of extra text that may or may not solve your problem. The chore then becomes PR reviews of tons of iffy code, and if you merge too much of it, after too long your codebase will be a bloated mess that even the craftiest prompts won't untangle.
It's best to use to brainstorm and implement very targeted prompts, set and forget is crazy.
Completely agree. The quoted strategy only works for small hobbyist codebases.
Don't sleep on using Claude Code to improve your Claude Code config. Switch to plan mode and try the following prompt:
read the document at https://blog.sshh.io/p/how-i-use-every-claude-code-feature and tell me how to improve my Claude code setup
"Claude Code isn’t just an interactive CLI; it’s also a powerful SDK for building entirely new agents—..."
Em dash and "it's not X, it's Y" in one sentence. Tired of reading posts written by AI. Feels disrespectful to your readers
> /clear + /catchup (Simple Restart): My default reboot. I /clear the state, then run a custom /catchup command to make Claude read all changed files in my git branch.
I've found myself doing similar workarounds. I'm guessing anthropic will just make the /compact command do this instead soon enough.
Kinda sad if 3000 words is now considered "too long to read through rather use as reference" but some interesting points, I'd be keen to see an even longer version with actual examples instead of placeholder ones.
> If you’re not already using a CLI-based agent like Claude Code or Codex CLI, you probably should be.
Are the CLI-based agents better (much better?) than the Cursor app? Why?
I like how easy it is to get Cursor to focus a particular piece of code. I select the text and Cmd-L, saying "fix this part, it's broken like this ____."
I haven't really tried a CLI agent; sending snippets of code by CLI sounds really annoying. "Fix login.ts lines 148-160, it's broken like this ___"
As fascinating as these tools can be - are we (the industry) once again finding something other than our “customer” to focus our brains on (see Paul Graham’s “Top idea in your mind” essay)?
Man, I just want to point out how different programming has become in 2 years.
We are literally having to play mind games with our tooling now to convince and coax it into doing certain things. I swear we are not far off from having to call in sick to work because your LLM "is going through a lot right now and just needs a mental health break".
> The Takeaway: Skills are the right abstraction. They formalize the “scripting”-based agent model, which is more robust and flexible than the rigid, API-like model that MCP represents.
Just to not confuse, MCP is like an api but the underlying api can execute an Skill. So, its not MCP vs Skill as a contest. It's just the broad concept of a "flexible" skill vs "parameter" based Api. And again parameter based APIs can also be flexible depending on how we write it except that it lacks SKILL.md in case of Skills which guides llm to be more generic than a pure API.
By the way, if you are a Mac user, you can execute Skills locally via OpenSkills[1] that I have created using apple contianers.
1. OpenSkills -https://github.com/BandarLabs/open-skills
Crazy how fast Claude Code is evolving, every week there’s something new to learn, and it just keeps getting better.
I use claude code every day, and havent had a chance to dig super deep into skills, but even though ive read a lot of people describe them and say they're the best thing so far, I still dont get them. Theyre things the agent chooses to call right? They have different permissions? is it a tool call with different permissions and more context? I have yet to see a single post give an actual real-world concrete example of how theyre supposed to be used or a compare and contrast with other approaches.
Blog posts like this would really benefit from specific examples. While I can get some mileage out of these tools for greenfield projects, I'm actually shocked that this has proven useful with projects of any substantial size or complexity. I'm very curious to understand the context where such tools are paying off.
Does anyone else struggle with getting Claude to follow even the simplest commands in CLAUDE.md? I’ve completely give up on maintaining it because there’s a coin flip chance it disregards even the simplest instructions. For instance, (after becoming increasingly exasperated and whittling it down over and over), my CLAUDE file now has a single instruction, which says that any ai generated one-off script should be named <foo>.aigen.ts, and I can’t get Claude to follow something as simple as that! It does sometimes, but half the time it disregards the instructions.
I use Claude all the time, and this is probably my biggest issue with it. I just workaround by manually supplying context in prompts, but it’s kind of annoying to do so.
Does anyone else struggle with this or am I just doing something horribly wrong?
> Generally my goal is to “shoot and forget”—to delegate, set the context, and let it work. Judging the tool by the final PR and not how it gets there.
This feels like a false economy to me for real sized changes, but maybe I’m just a weak code reviewer. For code I really don’t care about, I’m happy to do this, but if I ever need to understand that code I have an uphill battle. OTOH reading intermediate diffs and treating the process like actual pair programming has worked well for me, left me with changes I’m happy with, and codebases I understand well enough to debug.
Skills are also a convenient way for writing self-documenting packages. They solve the problem of teaching the LLM how to use a library.
I have started experimenting with a skills/ directory in my open source software, and then made a plugin marketplace that just pulls them in. It works well, but I don't know how scalable it will be.
Does anyone have any suggestions on making Claude prefer to use project internal abstractions and utility functions? My C++ project has a lot of them. If I just say something like "for I/O and networking code, check IOUtils.h for helpers" then it often doesn't do that. But mentioning all helper functions and classes in the context also seems like a bad idea. What's the best way? Are the new Skills a solution?
I feel like these posts are interesting, but become irrelevant quickly. Does anyone actually follow these as guides, or just consume them as feedback for how we wish we could interface with LLMs and the workarounds we currently use?
Right now these are reading like a guide to prolog in the 1980s.
Are there any of those CLI clients (coded in plain and simple C, or basic python/perl without 1 billion of expensive dependencies) able to access those 'coding AI' prompt anonymously then rate limited?
If no anonymous access is provided, is there a way to create an account with a noscript/basic (x)html/classic web browsers in order to get an API key secret?
Because I do not use web engines from the "whatng" cartel.
To add insult to injury, my email is self-hosted with IP literals to avoid funding the DNS people which are mostly now in strong partnership with the "whatng" cartel (email with IP literals are "stronger" than SPF since it does the same and more). An email is often required for account registration.
If the author is reading this, then I feel like it would be great if you could potentially open source your skills and Claude MD in a redacted way so these are actually viewable. The problem with a lot of these tutorials is, if I can call it a tutorial, is that we never get to see the actual skills or the Claude MD themselves, just a description of it.
I really enjoyed reading this. One thought I had on the issue of paths in Claude.md
My concern with hardcoding paths inside a doc, it will likely become outdated as the codebase evolves.
One solution would be to script it and have it run pre commit to regenerate the Claude.md with the new paths.
There probably is potential for even more dev tooling that 1. Ensure reference paths are always correct, 2. Enforces standard for how references are documented in Claude.md (and lints things like length)
Perhaps using some kind of inline documentation standard like jsdoc if it’s a ts file or a naming convention if it’s an Md file
Example:
// @claude.md // For complex … usage or if you encounter a FooBarError, see ${path} for advanced troubleshooting steps
I don't understand how people use the `git worktree` workflow. I get that you want to isolate your work, but how do you deal with dev servers, port conflicts and npm installs? When I tried it, it was way more hassle than it was worth.
I've been having good results with Roo Code/Cline + Claude Code as the provider. I feel like using CC CLI effectively requires manually recreating Roo/Cline
Are "agents" really as useful as the hype makes them out to be?
Most of the time I'm just pasting code blocks directly into raycast and once I've fixed the bug or got the properly transformed code in the shape that I aimed for, then I paste it back into neovim. Next i'm going to try out "opencode"[0], because I've heard some good things about it. For now, I'm happy with my current workflow.
Hooks are underutilized and will be critical for long-running and better agent performance. Excited to release Cupcake in the coming weeks. What I started building when i made the feature request for hooks.
"It shifts us from a “per-seat” license to “usage-based” pricing, which is a much better model for how we work. It accounts for the massive variance in developer usage (We’ve seen 1:100x differences between engineers)."
This is how we are doing it too, for the same reasons. For now, much easier to administer than trying to figure out who spends enough to get a real Claude Code seat. The other nice thing about using API keys is that you basically never hit rate limits.
What type of projects are you guys building? I bought Max and these features to try it out to build a more complex project (ROS2) and that does not seem to work out at all… HTML page, yes, embedded project not so much.
Just read it and the author say "do not use NEVER" in claude.md then in his sample claude.md there is NEVER the word, am I missing something?
Just my curiosity: Why are you producing so much code? Is it because it is now possible to do so with AI, or because you have a genuine need (solid business usecase) that requires a lot of code?
"All my stateless tools (like Jira, AWS, GitHub) have been migrated to simple CLIs." - How do you get Jira on the CLI?
Or use this solution and get fine-tuned context generated for each and every task just-in-time : devly.ai
Please stop expecting every engineer on the team to be an ai engineer just to get started with coding agents
Why are so many still using CC and not Codex
right on. i usually just tell it "hey go update this function to do [x]" in horribly misspelled english and then yell at it until it does it right
Hans@lhoest.eu
Enshittification needs its Moore's law.
No thanks. I rather write the code myself that use generated slop. I actually like to code and see little benefit in other peoples copypaste code (thats essentially what ai slop is really)
Good article