How to Structure a Claude Code Project that Thinks Like an Engineer 

Builders use Claude Code as an enhanced autocomplete system. They open a file, sort a immediate, and hope for the most effective. The system produces first rate output which typically reaches nice high quality. The output reveals inconsistent outcomes. The system loses observe of context and repeats its preliminary errors. 

The answer wants a extra organized undertaking, not an prolonged immediate.  

This text showcases a undertaking construction which develops into an AI-powered system used for incident response, that follows Claude Code’s finest practices. 

The Lie Most AI Builders Consider

Probably the most vital misunderstanding that builders have with AI as we speak is: 

“Merely use an LLM and also you’re completed!” 

Mistaken! AI is a system. Not a characteristic.

A production-grade AI system requires:

• information pipelines: ingestion → chunking → embedding
• retrieval: hybrid search with re-ranking
• reminiscence: semantic caching, in-memory recall
• routing: right supply choice with fallbacks
• era: structured outputs
• analysis: offline and on-line
• safety: enter and output safeguards
• observability: full question traceability
• infrastructure: async, container-based

Most builders cease at API calls. That’s simply the primary degree! What’s not often mentioned:
repository construction determines how properly Claude Code helps you construct these layers.

Repair the construction. The whole lot else falls in place.

AI Incident Response System

This undertaking can be a cloud-based incident administration system powered by AI. I’ll be calling it respondly.

• Features: alert ingestion, severity classification, runbook era, incident routing, decision monitoring.
• Focus: not the system, however repository design.
• Function: present how construction allows Claude Code to function with context, guidelines, and workflows.
• Listing construction: reference sample under. Relevant to any AI system.

Let’s analyze how the general construction creates a greater expertise with Claude Code after which analyze each bit of the construction. 

The 4 Issues Each Claude Code Challenge Wants

Earlier than diving into creating folders, let’s evaluation the essence of Claude Code. With the intention to assume like an engineer, Claude Code primarily wants 4 items of knowledge: 

• The Why – what this element does and why it exists 
• The Map – the place every little thing is situated 
• The Guidelines – what’s permitted and what’s prohibited 
• The Workflow – how work is accomplished 

All of the folders within respondly/ listing performs one of many above roles. There is no such thing as a unintended folder placement.

CLAUDE.md: ROOT Reminiscence

CLAUDE.md is among the most crucial recordsdata for this undertaking, not documentation however mainly the mannequin’s reminiscence. Claude is taking a look at CLAUDE.md when it begins every time. You’ll be able to consider it like giving a brand new engineer an summary of the system on day one (besides Claude is given it each time). You have to be temporary, to the purpose and hold it to max three sections. 

What respondly/CLAUDE.md incorporates:

That’s all there may be to it. There aren’t any philosophies or prolonged descriptions. It’s all simply to inform the mannequin. 

If CLAUDE.md will get too lengthy, then the mannequin is not going to have the flexibility to comply with the essential directions it’s presupposed to comply with. Readability is at all times extra necessary than dimension. 

.claude/abilities: Reusable Skilled Modes

On this folder, it’s simple to see how Claude Code transitions from generalist to specialist. Reusable instruction codes allow Claude to create workflows that are repeatable. 

When Claude learns a brand new course of, there’s no want to clarify it every time. Outline it as soon as, then Claude will load that course of on demand. Claude ships with three distinctive abilities: 

1. triage-review/SKILL.md: The way to precisely verify severity of alerts, escalate, and evaluation for false optimistic patterns and whether or not or not the alert has a classification code that precisely describes the alert. 
2. runbook-gen/SKILL.md: The way to generate a Runbook. Particulars on output format, required fields, and tone can be included within the directions. 
3. eval-run/SKILL.md: The way to run the offline analysis pipeline. Contains metrics to make use of, thresholds that may set off a evaluation, and directions for logging outcomes. 

This offers everybody engaged on the undertaking with Claude Code, a constant, high-quality output from all customers, because it pertains to Claude’s use and execution. 

.claude/guidelines: Guardrails That By no means Overlook

Fashions, as you recognize, will typically neglect. Hooks and guidelines is not going to. The foundations listing incorporates the principles that MUST ALWAYS occur, no want for anybody to be reminded. 

• code-style.md will be sure that all formatting, import ordering, sort and type necessities are adopted for ALL python recordsdata. 
• testing.md will outline when exams ought to run (and shield what modules), how a lot take a look at protection should be achieved to go (i.e. it units the benchmark on protection after which nothing else will matter). 

Take into account the principles NON-NEGOTIABLES which might be inherently a part of the undertaking. Due to this fact, any undertaking created from Claude will mechanically embrace the principles with none reminders. 

.claude/Docs: Progressive Context, Not Immediate Overload

You do not want to place all the knowledge into one single immediate. This creates an anti-pattern. Reasonably, construct a documentation that Claude can entry the required sections on the applicable time. The respondly/docs listing consists of: 

• structure.md – general design, relationship between parts, information stream diagrams 
• api-reference.md – endpoint specs, request/response schema, authentication patterns 
• deployment.md – infrastructure setup, atmosphere variables, Docker Compose setup 

Claude doesn’t want to recollect all this documentation; it solely must know the place to acquire the knowledge it requires. Due to this fact, this alone will scale back a considerable variety of errors. 

Native CLAUDE.md Information: Context for Hazard Zones

There are specific areas of any given codebase that comprise hidden complexity. Although on the floor, they initially appear quite easy, they aren’t. 

For respondly/, these areas of complexity are as follows: 

• app/safety/ – immediate injection prevention mechanisms, content material filtering strategies, output validation processes 
• app/brokers/ – orchestration logic for LLMs, calling exterior instruments, and adaptive routing of requests 
• analysis/ – validity of golden dataset, correctness of analysis pipeline 

Every of those areas has its personal native CLAUDE.md file: 

App/safety/CLAUDE.md
app/brokers/CLAUDE.md
analysis/CLAUDE.md 

Inside these recordsdata, the CLAUDE system will get a transparent understanding of what elements of this space pose a risk, what errors to keep away from, and what conventions are important on the time CLAUDE is working inside the confines of that listing. 

This remoted course of reduces the prevalence of LLM-enabled bugs considerably inside high-stakes modules. 

Why the brokers/Layer is the Actual Intelligence Layer?

Respondly/ has created a multi-agent framework. Contained in the respondly/brokers/ folder are 4 recordsdata:  

• triage_agent.py, which classifies alerts primarily based on severity and makes use of a structured output and a golden dataset to repeatedly recalibrate itself;  
• runbook_generator.py to create incident runbooks by determining what the duty is after which producing step-by-step directions primarily based on a “be taught and adapt” mannequin using LLMs in addition to templates and validates outputs;  
• adaptive_router.py, which selects an applicable information supply to question (i.e. PagerDuty, Datadog, or inner knowledgebase) primarily based on context;  
• instruments/, which is the place all exterior integrations plugged into the system reside. Every software is a standalone module, thus creating a brand new integration merely requires an addition of 1 file. 

It’s these traits that set an AI manufacturing system aside from an AI demo system (i.e. The flexibility to be modular with respect to intelligence; to have the ability to run varied exams on every particular person element of the system; and the flexibility to view the chain of occasions that led as much as a specific determination being made). 

The Shift That Adjustments The whole lot

What most people are inclined to overlook: 

Prompting is a momentary measure, whereas construction is a long-lasting criterion. 

An expertly written immediate will solely final you all through one particular person session, nonetheless an expertly constructed repository will final for everything of the undertaking.

While you undertaking is correctly structured: 

• Claude understands the aim of the system with out having to be advised. 
• Claude at all times abides by the established coding requirements in use. 
• Claude steers away from any dangerous modules with out being particularly warned towards the utilization of stated module. 
• Claude can implement complicated workflows at a gradual charge on a session-by-session foundation 

This isn’t a chatbot. That is an engineer who’s native to the undertaking. 

Conclusion

Probably the most vital mistake individuals make whereas growing AI is treating it as a comfort or superior search characteristic. Claude just isn’t that; it’s a reasoning engine, which requires context, construction, and reminiscence. Every of the respondly/ folders solutions one query: What does Claude must make his judgment on this second? If you’re constant along with your reply, it’s going to not be only a software; you should have created an engineer inside your codebase. 

The execution plan is easy: create a grasp CLAUDE.md, develop three abilities to be reused for repetitive processes. Then set up guidelines for what you can’t change; drop a set of native context recordsdata in your 4 largest modules to start out the creation of your structure. After you may have created these 4 recordsdata, you may have established your foundational constructing blocks for improvement. Then you must deal with having your structure in place earlier than scaling up the variety of recordsdata and/or features that you simply create to help your utility. You’ll discover that every little thing else will comply with. 

Often Requested Questions