Claude Code: the framework that turns AI into engineers

The False Simplicity of AI Systems

In the world of artificial intelligence developers, a persistent misconception exists: that simply using a large language model (LLM) is enough to solve all problems. This simplistic view obscures the true complexity of AI systems. In reality, a high-performing AI system is not limited to a single functionality but resembles a complex ecosystem.

For an AI system to reach a sufficient quality level for production, several elements must be integrated. These include data pipelines that ensure the ingestion, fragmentation, and integration of information. Research must be hybrid, with re-ranking mechanisms. Memory should include semantic caches and memory recalls. Routing must be capable of selecting appropriate sources while offering alternatives. Generation should produce structured outputs, while evaluation must occur both offline and online. Security must protect inputs and outputs, and observability should allow for complete traceability of requests. Finally, the infrastructure must be asynchronous and container-based.

Unfortunately, many developers settle for simple API calls, ignoring that this is just the first step. The structure of the repository plays a crucial role in how Claude Code can help build these different layers. A well-defined structure is the keystone of success.

An AI-Based Incident Management System

Imagine an incident management project powered by artificial intelligence and hosted in the cloud, which we will call respondly. This system would focus on ingesting alerts, classifying their severity, generating runbooks, routing incidents, and tracking resolutions. The primary goal would not be the system itself, but rather how the repository is structured.

The structure of the directory is essential for enabling Claude Code to operate with the appropriate context, rules, and workflows. This reference model is applicable to any AI system.

The Four Pillars of Claude Code

For Claude Code to function like an engineer, four pieces of information are essential:

• The Why: the purpose of each component
• The Map: the location of each element
• The Rules: what is allowed and what is not
• The Workflow: how the work is done

Each folder within the respondly/ directory plays one of these roles. Nothing is left to chance.

CLAUDE.md: The Central Memory

The CLAUDE.md file is crucial for the project. It is not just simple documentation but the memory of the model. Claude consults this file at every startup, like an engineer receiving an overview of their work on the first day. This file must be concise, precise, and limited to a maximum of three sections.

The content of respondly/CLAUDE.md is minimalist, without philosophies or lengthy descriptions. It serves solely to inform the model. If this file becomes too long, the model may fail to follow critical instructions. Clarity always takes precedence over quantity.

.claude/skills: Reusable Skills

In the .claude/skills folder, Claude Code transitions from generalist to specialist through reusable instruction codes. These skills allow Claude to create repeatable workflows without the need for constant re-explanations.

Claude possesses three unique skills:

• triage-review/SKILL.md: checking the severity of alerts and reviewing false positives
• runbook-gen/SKILL.md: generating runbooks with detailed instructions
• eval-run/SKILL.md: executing the offline evaluation pipeline

These skills ensure consistent, high-quality output for all users of Claude Code.

.claude/rules: Immutable Rules

Models can forget, but rules and hooks do not. The rules directory contains directives that must always be followed.

• code-style.md: ensures compliance with formatting and type requirements for all Python files
• testing.md: defines when tests should be executed and the required coverage level

These rules are non-negotiable and are an integral part of the project. Any Claude project automatically includes these rules.

.claude/Docs: Progressive Documentation

There is no need to overload a prompt with too much information. Instead, documentation should be accessible at the right moment. The respondly/docs directory includes:

• architecture.md: overall design and data flow diagrams
• api-reference.md: specifications for endpoints and authentication models
• deployment.md: infrastructure configuration and environment variables

Claude does not need to memorize all this documentation but simply needs to know where to find the necessary information, thereby reducing errors.

Local CLAUDE.md Files: Managing Complex Areas

Certain parts of the code may contain hidden complexity. For respondly/, these areas include:

• app/security/: preventing prompt injections and validating outputs
• app/agents/: orchestrating LLMs and adaptive routing
• evaluation/: correcting the evaluation pipeline

Each area has its own local CLAUDE.md file, allowing Claude to understand potential threats and errors.

The Agents Layer: The Heart of Intelligence

The multi-agent framework of respondly/ consists of several key files:

• triage_agent.py: classifies alerts according to their severity
• runbook_generator.py: creates incident runbooks
• adaptive_router.py: selects the appropriate data source
• tools/: integrates external tools

These features distinguish a production AI system from a simple demonstration system.

Structure: A Lasting Asset

Many overlook the importance of structure. A well-designed prompt is temporary, while a solid structure is enduring. Once your project is well-structured, Claude understands the purpose of the system without further explanations.