How to Make a Claude Code Project Work as a Developer

Developers use Code Claude as an advanced auto-completion system. They open a file, type in information, and hope for the best. The program produces decent output that sometimes reaches high quality. The output shows inconsistent results. The system loses track of context and repeats its initial mistakes.

The solution requires more systematic projectnot i more information.

This article shows the project structure being developed into an AI-powered system used for incident response, following Claude Code best practices.

Lies Many AI Developers Believe

The most important misunderstandings developers have with AI today:

“Just apply LLM and you’re done!”

It’s wrong! AI is a system. It is not a feature.

A production-grade AI system needs:

• data pipes: Import → merge → embed
• to retrieve: mixed search by repositioning
• memory: semantic caching, memory cache
• route: correct source selection with updates
• generation: systematic results
• check: offline and online
• security: installing and removing protection
• appearance: full traceability of the query
• infrastructure: async, container-based

Most developers stop at API calls. That’s just the first level! Less commonly discussed:
The structure of the repository determines how Claude Code helps you build these layers.

Adjust the layout. Everything else is in place.

An AI incident response system

The project will be a cloud-based incident management system powered by AI. I will be calling answer.

• Activities: alert entry, severity classification, runbook generation, incident routing, resolution tracking.
• Focus: not the program, but the cache design.
• Purpose: show how the structure makes Claude Code work with context, rules, and workflows.
• Directory structure: reference pattern below. Works on any AI system.

Let’s analyze how the architecture as a whole makes for a better experience with Claude Code and then analyze each piece of the architecture.

Four Things Every Claude Code Project Needs

Before we get into creating folders, let’s review the core of Claude’s code. To think like an engineer, Claude Code requires four pieces of knowledge:

• Why – what this component does and why it exists
• Map – where everything is
• Laws – what is allowed and what is not allowed
• Work flow – how the work is completed

All the folders inside the respondly/ directory performs one of the above roles. No accidental folder placement.

CLAUDE.md: ROOT Memory

CLAUDE.md is one of the most important files for this project, not the documentation but basically the memory of the model. Claude watches CLAUDE.md when it starts each time. You can think of it as giving a new developer an overview of the system on day one (except that Claude is given it all the time). You should be short, to the point and keep it to three paragraphs.

What respondly/CLAUDE.md contains:

That’s all there is to it. No philosophies or long explanations. Everything is simple inform the model.

If CLAUDE.md will be too long, then the model will not be able to follow the critical instructions it has to follow. Clarity is more important than size.

.claude/skills: Reusable Expert Methods

In this folder, it is easy to see how Claude Code changes from generalist to specialist. Reusable command codes enable Claude to create repeatable workflows.

When Claude learns a new technique, there is no need to explain it each time. Define it once, and Claude loads that process on demand. Claude ships with three unique abilities:

1. triage-review/SKILL.md: How to accurately assess alert severity, escalation, and updates to find false positive patterns and whether an alert has a classification code that accurately describes the alert.
2. runbook-gen/SKILL.md: How to make a Runbook. Details on the output format, required fields, and tone will be included in the instructions.
3. eval-run/SKILL.md: How to use offline test pipeline. It includes metrics to be used, thresholds that will trigger a review, and instructions for logging results.

This gives everyone working on the project with Claude Code, a consistent, high-quality result for all users, as it relates to the use and execution of Claude.

.claude/rules: The Unforgettable Guardians

Models, as you know, will always be forgotten. Hooks and rules will not. The list of rules contains the rules you MUST ALWAYS do, no one needs to be reminded.

• code-style.md will ensure that all formatting, import ordering, type and form requirements are followed by ALL python files.
• check.md it will define when the test should run (and protect which modules), how much the test should achieve in order to pass (ie it sets a benchmark on coverage that wouldn’t matter otherwise).

Consider the NON-NEGOTIATION rules that are part of the project. Therefore, any project created from Claude will automatically include the rules without any reminders.

.claude/Documents: Persistent Context, Not Instant Loading

You do not need to include all information in one notification. This creates an anti-pattern. Instead, create documents that Claude can access the necessary sections at the right time. I reply/documents directory contains:

• properties.md – overall design, relationships between components, data flow diagrams
• api-reference.md – Endpoint specification, request/response schema, authentication patterns
• shipping.md – infrastructure setup, environment variables, Docker Compose setup

Claude does not need to memorize all these texts; it only needs to know where to find the information it needs. Therefore, this alone will reduce a large number of errors.

CLAUDE.md Location Files: Content for Hazardous Locations

There are certain areas of any given codebase that contain hidden complexity. Although at first glance, they seem straightforward, they are not.

Because answer/these complex areas are as follows:

• app/security/ – rapid injection prevention methods, content filtering methods, output validation procedures
• application/agents/ – Orchestration logic for LLMs, calling external tools, and routing requests
• checking/ – gold dataset validity, test pipeline accuracy

Each of these places has its place CLAUDE.md file:

App/security/CLAUDE.md
app/agents/CLAUDE.md
evaluation/CLAUDE.md 

Within these files, the CLAUDE system gets a clear understanding of which aspects of the site are a threat, which mistakes to avoid, and which conventions are important when CLAUDE operates within the boundaries of that information.

This isolated process reduces the occurrence of LLM-enabled bugs significantly among high-value modules.

Why Agents/Layer Is Real Intelligence Layer?

Reply/ created a multi-agent framework. Within the reply/agents/ folder has 4 files:

• triage_agent.pythat categorizes alerts based on severity and uses programmed output and gold datasets to continuously re-rate them;
• runbook_generator.py creating event runbooks by determining what the task is and generating step-by-step instructions based on the “learn and adapt” model using LLMs and templates and verifying the results;
• adaptive_router.pythat selects the appropriate data source to query (ie, PagerDuty, Datadog, or an internal database) based on context;
• tools/which is where all external integrations connected to the system reside. Each tool is an independent module, thus creating a new integration only requires the addition of 1 file.

It is these features that set a production AI system apart from an AI demo system (i.e. The ability to be modular in terms of intelligence; the ability to perform various tests on each part of the system; and the ability to observe the chain of events that led to a particular decision).

The Shift That Changes Everything

What many people tend to overlook:

Appreciation is a temporary measure, while structure is a permanent goal.

Professionally written information will only last for one session, but a professionally created archive will last for the entire project.

If the project is well planned:

• Claude understands the purpose of the program without being told.
• Claude always follows the established coding standards used.
• Claude avoids any harmful modules without being specifically warned about the use of said module.
• Claude can implement complex workflows at a fixed rate on a session-by-session basis

This is not a chatbot. This is the developer from this project.

The conclusion

The most important mistake people make while developing AI is to treat it as a simple or advanced search feature. Claude is not; it is a thinking engine, which requires context, structure, and memory. Each answer/folder answers one question: What does Claude need to make his judgment at this time? If you are consistent with your answer, it will no longer be just a tool; you will have created a developer within your codebase.

The implementation plan is straightforward: create the main CLAUDE.md, develop three capabilities that will be reused for repetitive processes. Then set rules for what you cannot change; download a set of local context files for your main main modules to start the creation of your architectures. After you’ve created those four files, you’ve created your basic building blocks for development. Then you should focus on having your architecture in place before increasing the number of files and/or functions you create to support your application. You will find that everything else will follow.

Frequently Asked Questions