from Hacker News

Field Notes from Shipping Real Code with Claude

by diwank on 6/7/25, 6:11 PM with 99 comments

  • by diwank on 6/8/25, 12:49 AM

    Author here: To be honest, I know there are like a bajillion Claude code posts out there these days.

    But, there are a few nuggets we figured are worth sharing, like Anchor Comments [1], which have really made a difference:

    ——

      # CLAUDE.md

  ### Anchor comments

  Add specially formatted comments throughout the codebase, where appropriate, for yourself as inline knowledge that can be easily `grep`ped for.

  - Use `AIDEV-NOTE:`, `AIDEV-TODO:`, or `AIDEV-QUESTION:` as prefix as appropriate.

  - *Important:* Before scanning files, always first try to grep for existing `AIDEV-…`.

  - Update relevant anchors, after finishing any task.

  - Make sure to add relevant anchor comments, whenever a file or piece of code is:

  * too complex, or  
  * very important, or  
  * could have a bug
    ——

    [1]: https://diwank.space/field-notes-from-shipping-real-code-wit...

  • by kasey_junk on 6/7/25, 10:46 PM

    One of the exciting things to me about the ai agents is how they push and allow you to build processes that we’ve always known were important but were frequently not prioritized in the face of shipping the system.

    You can use how uncomfortable you are with the ai doing something as a signal that you need to invest in systematic verification of that something. As a for instance in the link, the team could build a system for verifying and validating their data migrations. That would move a whole class of changes into the ai relm.

    This is usually much easier to quantify and explain externally than nebulous talk about tech debt in that system.

  • by m_kos on 6/8/25, 7:27 PM

    Good read – I have learned something new.

    I have been having a horrible experience with Sonnet 4 via Cursor and Web. It keeps cutting corners and misreporting what it did. These are not hallucinations. Threatening it with deletion (inspired by Anthropic's report) only makes things worse.

    It also pathologically lies about non-programming things. I tried reporting it but the mobile app says "Something went wrong. Please try again later." Very bizarre.

    Am I the only person experiencing these issues? Many here seem to adore Claude.

  • by nxobject on 6/8/25, 4:49 PM

    As I read (and appreciate) your documentation tips, I don’t even think they have to be labeled as AI-specific! ‘CLAUDE.md’ seems likely it could just as be ‘CONVENTIONS.md’, and comments to ‘AI’ could just as be comments to ‘READER’. :) Certainly I would appreciate comments like that when reading _any_ codebase, especially as an unfamiliar contributor.

  • by dkobia on 6/8/25, 12:18 PM

    Thank you for writing this. Many software developers on HN are conflicted about ceding control of software development to LLMs for many reasons including the fact that it feels unstructured and exploratory rather than rigidly planned using more formal methodologies.

    There's a good middle ground where the LLMs can help us solve problems faster optimizing for outcomes rather than falling in love with solving the problem. Many of us usually lose sight of the actual goal we're trying to achieve when we get distracted by implementation details.

  • by wonger_ on 6/8/25, 2:11 AM

    Some thoughts:

    - Is there a more elegant way to organize the prompts/specifications for LLMs in a codebase? I feel like CLAUDE.md, SPEC.mds, and AIDEV comments would get messy quickly.

    - What is the definition of "vibe-coding" these days? I thought it refers to the original Karpathy quote, like cowboy mode, where you accept all diffs and hardly look at code. But now it seems that "vibe-coding" is catch-all clickbait for any LLM workflow. (Tbf, this title "shipping real code with Claude" is fine)

    - Do you obfuscate any code before sending it to someone's LLM?

  • by skerit on 6/8/25, 9:53 AM

    Very interesting, I'm going to use some of these ideas in my CLAUDE.md file.

    > One of the most counterintuitive lessons in AI-assisted development is that being stingy with context to save tokens actually costs you more

    Something similar I've been thinking about recently: For bigger projects & more complicated code, I really do notice a big difference between Claude Opus and Claude Sonnet. And Sonnet sometimes just wastes so much time on ideas that never pan out, or make things worse. So I wonder: wouldn't it make more sense for Anthropic to not differentiate between Opus and Sonnet for people with a Max subscription? It seems like Sonnet takes 10-20 turns what Opus can do in 2 or 3, so in the end forcing people over to Sonnet would ultimately cost them more.

  • by lispisok on 6/8/25, 2:19 AM

    I think most of this is good stuff but I disagree with not letting Claude touch tests or migrations at all. Handing writing tests from scratch is the part I hate the most. Having an LLM do a first pass on tests which I add to and adjust as I see fit has been a big boon on the testing front. It seems the difference between me and the author is I believe whether code was generated by an LLM or not the human still takes ownership and responsibility. Not letting Claude touch tests and migrations is saying you rightfully dont trust Claude but are giving ownership to Claude for Claude generated code. That or he doesn't trust his employees to not blindly accept AI slop, the strict rules around tests and migrations is to prevent the AI slop from breaking everything or causing data loss.

  • by Artoooooor on 6/8/25, 2:06 AM

    I finally decided few days ago to try this Claude Code thing in my personal project. It's depressingly efficient. And damn expensive - I used over 10 dollars in one day. But I'm afraid it is inevitable - I will have to pay tax to AI overlords just to be able to keep my job.

  • by remram on 6/8/25, 5:38 PM

    The 2.3 MB picture at the top loaded comically slowly even on wifi.

  • by mgraczyk on 6/8/25, 6:13 PM

    Good post, the only part I think I disagree with is

    > Never. Let. AI. Write. Your. Tests.

    AI writes all of my tests now, but I review them all carefully. Especially for new code, you have to let the AI write tests if you want it to work autonomously. I explicitly instruct the AI to write tests and make sure they pass before stopping. I usually review these tests while the AI is implementing the code to make sure they make sense and cover important cases. I add more cases if they are inadequate.

  • by nilirl on 6/8/25, 3:53 AM

    Lot of visual noise because of model specific comments. Or maybe that's just the examples here.

    But as a human, I do like the CLAUDE.md file. It's like documentation for dev reasoning and choices. I like that.

    Is this faster than old style codebases but with developers having the LLM chat open as they work? Seems like this ups the learning curve. The code here doesn't look very approachable.

  • by indigodaddy on 6/13/25, 9:47 AM

    Can anyone recommend a specific YouTube video that really shows how to use Claude Code effectively in your workflow?

  • by __mharrison__ on 6/8/25, 7:45 PM

    Thanks for the post. It's very interesting time navigating the nascent field of AI assisted development.

    Curious if the author (or others) tried other tools / models.

  • by meeech on 6/8/25, 1:01 AM

    Honest question: approx what percent of the post was human vs machine written?

  • by djrockstar1 on 6/8/25, 1:24 AM

    [flagged]