The no-bullshit guide to Agentic Engineering Agentic engineering, a methodology combining system prompt design via CLAUDE.md files and agentic loop design, enables production-ready software development in hours instead of months, according to a guide written for the engineering team at Better Stack. The guide asserts that AI is ready for most software tasks today and that engineers should assume AI capability rather than doubt it, emphasizing that CLAUDE.md is the highest return-on-investment file in a codebase and should be shared team-wide in Git. It distinguishes agentic engineering from vibe coding, stating that the former produces secure, production-ready code of human-level quality or better. The no-bullshit guide to Agentic Engineering Practical guide to shipping production-ready software in hours instead of months. Originally written for the engineering team at Better Stack. A practical mental model If you ever find yourself saying: “AI is not good enough yet to do action ”, please automatically assume you’re wrong. It’s just practical to do so. It forces you to think “ how do I make AI do this?” AI is ready today, except for real-time video calls. So the odds are you just don’t know how to configure it properly. Just because you installed Claude Code doesn’t mean you’re leveraging the full power of AI for software development. Always be learning : specifically, keep asking other engineers to show you their CLAUDE.md. What is “agentic engineering”? It’s a combination of 2 things: system prompt design = CLAUDE.md agentic loop design Is it just vibe coding? No. Vibe coding produces insecure throwaway code for your weekend projects. It’s ideal for prototyping. It replaced Figma as a tool to visualize ideas. Agentic engineering produces secure, production-ready code that is of the same quality as code written by humans, or better. Part 1: System prompt design = CLAUDE.md The real software engineering today happens in your CLAUDE.md. CLAUDE.md is the highest return-on-investment file in your entire codebase . If this is the first CLAUDE.md you’re writing, spend hours designing it: sentence by sentence. Never have a personal, locally stored CLAUDE.md. Always share your CLAUDE.md with your entire team directly in Git in the codebase. CLAUDE.md is the new meta programming. Dear engineering managers : for the first time in the history of software engineering, you can now directly influence what kind of code your human colleagues contribute Historically, your only option would be to write a GitHub pull request review comment “Bob, please prefer to do X over Y next time”. Today, you just re-configure everyone’s CLAUDE.md instead. Your team will continue using Claude Code the same way and magically produce better code Signs that your CLAUDE.md is incorrectly designed Claude will say “Exploring your code base to understand X…” Your CLAUDE.md doesn’t have a ‘routing table’ section that would reference other markdown files for documentation, describe codebase components, and link to adjacent codebases. Claude will say “Writing a memory about X…” You haven’t configured Claude to write shared documentation in your codebase. This is problematic because your colleagues won’t be able to leverage the same agent memories when their agents run, so they’ll be running into the same mistakes you already did. How to write your CLAUDE.md Your CLAUDE.md must include 3 things: Description : 1-sentence description of the codebase. Rules: Behaviors the agent should and shouldn’t do Routing table: References to where to find additional knowledge Common mistake: Do not include specific knowledge in your CLAUDE.md. CLAUDE.md is for behavioral rules = meta programming in English; it’s not a place for product documentation. Why? CLAUDE.md is your system prompt: it gets included at the start of every session of every sub-agent, always. Unless a particular fact is required for every single session, it doesn’t belong to CLAUDE.md. Irrelevant words in your CLAUDE.md can easily make your agents worse. 1. 1-sentence codebase description Assume common sense and keep it concise. “This is a Ruby on Rails + PostgreSQL + Redis backend for an iOS application that <… .” Don’t waste your tokens on general knowledge: No need to explain the Model-View-Controller pattern. Claude knows what a typical Rails codebase looks like. 2. Agent rules = meta-programming in English Now the fun part. Personally, I find a properly designed CLAUDE.md to be way more impactful than an underlying model upgrade e.g., Opus → Fable . Below are a few fundamental rules I find incredibly helpful. Do you use other tricks I haven’t mentioned here? Please tweet at me at x.com/jurajmasar http://x.com/jurajmasar . Rule 1: test-driven development “Always use TDD: test-driven development”. Thanks to TDD, your agents will keep getting better on their own as the codebase grows, feature by feature. The more tests, the more implicit rules for what the end result should look like. Your agents are really good at writing very fast unit tests. They’re also amazing at selecting just the right subset of tests to run to validate a particular code change. You will thus see your agent launching tests on their own when implementing a new feature, detecting a failure and improving the code on their own, without any impact from you. That’s your first taste of an agentic loop More on that later. Even if a test is not executed, its definition alone describes how the software should work. When the agent loads the test file into the LLM context, it becomes implicit documentation for what the behavior should be. Rule 2: 1-sentence class and method description “Write a 1-sentence description on top of all classes and methods: Write a succinct but thorough summary of what a class or a method does right above its definition.” In agentic coding, repetition is better than abstraction. The in-code documentation is helpful for humans interacting with the code, but, more importantly, it serves as an additional layer of context to ground the agent's execution. Rule 3: Document non-trivial hacks “Document all non-trivial hacks or monkey-patches directly in code if scattered among multiple files. Always reference the other related files.” How does the agent know that a particular line of code is meant to be used with a different line of code in a different file? Excluding conventions, such as an MVC pattern, its only chance is to grep the code. But if grep doesn’t find it, it doesn’t exist. Mainly when using dynamic languages. Hence if you don’t document directly in code in both files that these 2 lines serve the same purpose, that information will be forever lost. It will be only implicitly stored in git commit history: the agent could theoretically find that the two lines were introduced in the same commit, but that’s way too much work so this fact will be missed unless the agent is specifically debugging an error and thinking with ultracode effort. Rule 4: Documentation “Write end-user documentation to docs/user documentation.md. Write a public API documentation into docs/api documentation.rb, make it production-ready so that it can be directly shared with customers; don’t include internal information there. Write a high-level internal documentation about the implementation into docs/internal documentation.md. Never write any local memories. You must include the memories in one of these documentation markdown files instead. If needed, create additional files in the docs/ {topic}.md directory and add them to git.” Repetition over abstraction . More documentation means more grounding for future sessions. Every new session is smarter than the previous one. The documentation must not live directly in your precious Claude.md as it doesn’t need to be loaded with every session. You never edit this documentation manually. Rule 5: Conventions “ Naming conventions:Always say “Sign in”, never “Log in”. Always say “team members”, never say “colleagues” or “users”. Always say “Remove”, never say “Delete”. Always say “We’ll”, never “we will”. Always say “e-mail”, never “email”. others UI conventions:The first