DEV Community: Thomas Tartrau

JSON vs Programmatic Tool Calling with Claude

Thomas Tartrau — Fri, 11 Sep 2026 16:54:27 +0000

When building an application with the Claude API, connecting tools is the first step toward a functional agent. The model can call functions, query databases, send messages. But how you wire those tools drastically changes performance, cost, and code complexity.

In 2026, the Claude API offers three distinct approaches. This article compares them with code, numbers, and practical experience from using all three.

The problem: round trips

Traditional tool calling works in a loop: the model requests a tool, your server executes it, sends back the result, the model reasons over the result, requests another tool, and so on. Each iteration is a full round trip with the model.

The problem becomes concrete as the number of tools grows. Checking expenses for 20 employees? 20 round trips. Every intermediate result piles into the context. According to Anthropic's measurements, tool definitions alone can consume over 134,000 tokens before any conversation in a multi-server setup.

Approach 1: JSON schema + manual loop

This is the original approach. You define each tool with a JSON schema, send the request to the API, parse the tool_use response, execute the tool, and send back the result.



client = anthropic.Anthropic()

tools = [{
    "name": "query_database",
    "description": "Execute a SQL query. Returns rows as JSON.",
    "input_schema": {
        "type": "object",
        "properties": {
            "sql": {"type": "string", "description": "SQL query"}
        },
        "required": ["sql"]
    }
}]

messages = [{"role": "user", "content": "What's the revenue by region?"}]

while True:
    response = client.messages.create(
        model="claude-sonnet-5",
        max_tokens=4096,
        tools=tools,
        messages=messages,
    )

    if response.stop_reason == "end_turn":
        break

    for block in response.content:
        if block.type == "tool_use":
            result = execute_sql(block.input["sql"])
            messages.append({"role": "assistant", "content": response.content})
            messages.append({
                "role": "user",
                "content": [{
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": json.dumps(result)
                }]
            })

The while True loop is the critical part. You handle the request/response cycle, parse tool_use blocks, accumulate messages, and manage error cases yourself.

Pros: full control over every step. You can log, filter results, inject business logic between calls.

Cons: lots of boilerplate. Every tool result passes through the model, even if it's just an intermediate value. With 10 tool calls, that's 10 full inference passes.

Approach 2: Tool Runner SDK

The Tool Runner is a helper in the official Anthropic SDKs (Python, TypeScript, Go, Java, C#, PHP, Ruby). It automates the agentic loop: tool definition, execution, conversation state management, and type validation.

In Python, the @beta_tool decorator generates the JSON schema from type hints and the docstring:

from anthropic import Anthropic, beta_tool

client = Anthropic()

@beta_tool
def query_database(sql: str) -> str:
    """Execute a SQL query on the sales database.

    Args:
        sql: SQL query to execute
    """
    rows = db.execute(sql)
    return json.dumps(rows)

runner = client.beta.messages.tool_runner(
    model="claude-sonnet-5",
    max_tokens=4096,
    tools=[query_database],
    messages=[{"role": "user", "content": "What's the revenue by region?"}],
)

for message in runner:
    print(message)

In TypeScript, two options: betaZodTool with Zod validation (recommended), or betaTool with a plain JSON schema:





const client = new Anthropic();

const queryDatabase = betaZodTool({
  name: "query_database",
  description: "Execute a SQL query on the sales database",
  inputSchema: z.object({
    sql: z.string().describe("SQL query to execute"),
  }),
  run: async (input) => {
    const rows = await db.execute(input.sql);
    return JSON.stringify(rows);
  },
});

const result = await client.beta.messages.toolRunner({
  model: "claude-sonnet-5",
  max_tokens: 4096,
  tools: [queryDatabase],
  messages: [{ role: "user", content: "What's the revenue by region?" }],
});

The Tool Runner handles the loop automatically: when Claude requests a tool, the runner executes it and sends back the result. No more while True, no manual tool_use block parsing.

Pros: less code, type safety with Zod or Python type hints, built-in error handling.

Cons: same execution model as the manual approach under the hood. Each tool call is still a round trip with the model. The gain is in DX, not performance.

Approach 3: programmatic tool calling

Programmatic tool calling changes the execution model. Instead of requesting one tool at a time through the API, Claude writes Python code that calls your tools directly inside a code execution container. Intermediate results stay in the container and only enter the model's context when Claude explicitly sends them.

To enable this approach, you need two things: include the code_execution tool in the request, and add allowed_callers to the tools Claude can call from code:

client = anthropic.Anthropic()

response = client.messages.create(
    model="claude-sonnet-5",
    max_tokens=4096,
    messages=[{
        "role": "user",
        "content": "Compare revenue across the West, East, and Central regions"
    }],
    tools=[
        {"type": "code_execution_20260120", "name": "code_execution"},
        {
            "name": "query_database",
            "description": "Execute a SQL query. Returns rows as JSON.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "SQL query"}
                },
                "required": ["sql"]
            },
            "allowed_callers": ["code_execution_20260120"]
        }
    ],
)

Claude then generates a Python script that calls query_database in a loop or in parallel via asyncio.gather, filters the results, and only sends back the summary:



results = {}
for region in ["West", "East", "Central"]:
    rows = json.loads(await query_database({
        "sql": f"SELECT SUM(revenue) as total FROM sales WHERE region = '{region}'"
    }))
    results[region] = rows[0]["total"]

best = max(results, key=results.get)
print(f"Highest revenue region: {best} ({results[best]} USD)")
print(f"Details: {json.dumps(results)}")

Instead of 3 model round trips, a single inference produced the code, and all 3 tool calls execute inside the container. The model only receives the final print() output.

Tools are exposed as async Python functions. The allowed_callers field controls who can call each tool:

Value	Behavior
`["direct"]`	Standard API call (default)
`["code_execution_20260120"]`	Call only from code execution
`["direct", "code_execution_20260120"]`	Both modes

Anthropic recommends choosing a single mode per tool to avoid ambiguity.

Pros: massive token and latency reduction. BrowseComp and DeepSearchQA benchmarks show +11% performance and -24% input tokens. On complex research tasks, average usage drops from 43,588 to 27,297 tokens, a 37% reduction.

Cons: requires the code_execution tool (beta). Containers have a limited lifetime (~5 minutes idle). Not available on Amazon Bedrock or Google Cloud. The field is not a security boundary: allowed_callers guides Claude but does not strictly block direct calls.

Comparison

Criterion	JSON + loop	Tool Runner SDK	Programmatic
Inferences per N tools	N	N	1 + returns
Intermediate tokens	In context	In context	In container
Code complexity	High	Low	Medium
Per-step control	Full	Limited	Via generated code
Latency	N x inference	N x inference	1 inference + exec
Type safety	Manual	Zod / type hints	N/A (generated code)
Availability	GA, all clouds	Beta, all clouds	Beta, direct API

When to use what

JSON + manual loop when you need fine-grained control between each tool call. For example: a workflow with human validation between steps, detailed logging, or conditional business logic. It's also the only option if you target Bedrock or Google Cloud without the Tool Runner.

Tool Runner SDK for most use cases. The code is cleaner, type validation is automatic, and the behavior is identical to the manual loop under the hood. This is the approach I use by default in my TypeScript and Python projects.

Programmatic tool calling when the number of tool calls per request is high or intermediate results are large. The typical example: aggregating data from 20 sources, filtering, and only returning the summary. It's also the most efficient approach for research tasks where Claude needs to explore and sort before concluding.

You can combine approaches. A tool marked ["direct"] will be called through the standard loop, while another marked ["code_execution_20260120"] will be orchestrated by the code. In the same project.

In practice

In CodeRift, I use the Tool Runner for review agents: each agent has 2-3 tools (read a file, search symbols, post a comment) and the number of calls is predictable. The Tool Runner eliminates boilerplate without sacrificing visibility.

For data exploration tasks in my IronFlow workflows, programmatic tool calling would be the right choice: an agent scanning 50 GitLab projects, filtering open MRs, and aggregating stats. The heavy lifting happens in the container, and only the summary enters the context.

The manual JSON approach stays for cases where the Tool Runner isn't available (unsupported SDK, or integration with a third-party framework that manages its own loop).

The choice isn't permanent. Start with the Tool Runner, migrate to programmatic when the token bill justifies it.

Automated code review with CodeRift

Thomas Tartrau — Fri, 11 Sep 2026 16:54:23 +0000

Code review is the bottleneck of most teams. The merge request is open, the author waits, the reviewer is busy with something else. When the review finally comes, it's often superficial: a quick glance at the diff, a "LGTM", merge. Logic bugs, security flaws and architecture violations slip through.

I built CodeRift to solve this problem. It's an automated code review platform that analyzes every GitLab merge request with a 7-step pipeline: diff parsing, AST analysis via tree-sitter, TOML rule engine, parallel specialized AI agents, cross-file correlation, false positive validation, and inline comment publishing directly in the MR. The whole thing is orchestrated by IronFlow, my Rust workflow engine.

The architecture

CodeRift follows an API + Workers model. The API (Rust/Axum/SQLx) handles persistence, GitLab OAuth authentication and webhooks. IronFlow workers poll the API for pending reviews, execute them, and post results.

The API/Worker separation is the same as IronFlow: the API owns persistence and never executes. Scaling means launching more workers.

The 7-step review pipeline

The review-merge-request workflow implements IronFlow's WorkflowHandler trait. Each step is an IronFlow operation with automatic retry and structured logging.

Steps 1-3: Preparation

The worker updates the review status in the database, posts a "review in progress" note on the GitLab MR, and sets the commit status to running. The developer immediately sees that the AI review has started.

ctx.operation("update-review-status", &update_status_op).await?;

ctx.http(
    "post-review-started",
    HttpConfig::post(&notes_url)
        .header("PRIVATE-TOKEN", &CONFIG.gitlab.bot_token)
        .json(serde_json::json!({ "body": review_started_message(language) })),
).await?;

commit_status::set(ctx, "set-commit-status-running", &proj,
    &payload.head_sha, payload.review_id, "running",
    "AI review in progress...").await?;

Step 4: The review pipeline (the core)

This is where the work happens. The pipeline follows this sequence:

TOML rules: CodeRift loads a set of rules embedded at compile time (include_dir!). Each rule targets a language, file patterns, and defines a regex pattern with exceptions. For example, the rust-unwrap rule detects .unwrap() in production code while excluding test files:

[[rules]]
id = "rust-unwrap"
severity = "error_handling"
score = 7
title = ".unwrap() in production code"
languages = ["rust"]
file_patterns = ["*.rs"]
exclude_patterns = ["*_test.rs", "tests/*"]
type = "regex"
pattern = '\.unwrap\(\)'
negative_pattern = '#\[test\]|#\[cfg\(test\)\]|mod tests'

Rules cover Rust, TypeScript, Python, Go, SQL, and common patterns (OWASP, prompt injection). Each project can add its own rules or disable server rules via a .coderift/context.md file.

AST analysis: tree-sitter parses the modified files and extracts a symbol index (definitions, references, cross-file edges). This index serves two purposes: building a dependency graph to group related files into the same chunks, and detecting structural patterns that regex can't see.

Chunking: files are grouped into chunks of 5 (configurable) for parallel review. When the dependency graph is available, related files stay in the same chunk to give the agent context on both sides of an interface.

Specialized AI agents: each chunk is reviewed by 3 agents in parallel, each with a different focus:

Agent	Model	Focus
Security	Opus 4.6	Injections, XSS, SSRF, access control, secrets
Bugs	Opus 4.6	Incorrect logic, edge cases, type errors
Performance	Sonnet 4.6	N+1, unnecessary allocations, algorithmic complexity

Each agent has a configurable USD budget and a maximum of 4 turns. The IronFlow provider manages execution and cost tracking. If an agent fails (schema error, timeout), the pipeline continues with results from the others.

let mut agent = Agent::new()
    .system_prompt(system)
    .prompt(prompt)
    .model(Model::OPUS_46)
    .max_turns(4)
    .max_budget_usd(budget)
    .output::<FindingsOutput>();

Cross-file correlation: a Sonnet 4.6 agent receives all findings from all chunks and identifies vulnerabilities that span multiple files. For example, an unvalidated input in a handler that reaches a SQL query in another file.

False positive validation: a final agent filters out irrelevant findings. Common false positives: an .unwrap() in test code, a pattern flagged in a comment, a finding targeting unchanged code, or a score inflated relative to actual risk.

Steps 5-6: Publishing

The worker posts results to the GitLab MR:

A summary with a walkthrough of the MR, files grouped by functional area, Mermaid sequence diagrams for non-trivial flows, and pre-merge checks (security, error handling, tests).
Inline comments on the relevant lines, with severity (Bug, Security, Performance, Error Handling, Suggestion), a criticality score (Critical/Major/Moderate/Minor), and a fix suggestion.

Step 7: Commit status

The GitLab commit status changes to success or failed. If the review has Critical findings, the pipeline can block the merge.

Findings

Each finding has a precise structure:

pub struct Finding {
    pub file: String,
    pub line: u32,
    pub end_line: Option<u32>,
    pub severity: Severity,    // Bug | Security | Performance | ErrorHandling | Suggestion
    pub score: u8,             // 0-10, maps to Critical/Major/Moderate/Minor
    pub title: String,
    pub comment: String,
    pub suggestion: Option<String>,
    pub analysis_chain: Vec<String>,
    pub ai_fix_prompt: Option<String>,
}

The analysis_chain field contains the agent's step-by-step reasoning. The ai_fix_prompt field is a ready-to-use prompt to automatically fix the finding.

Why not just call Claude Code?

The first version of this system used an n8n node that invoked Claude Code CLI. It worked for small MRs, but the limitations showed up fast:

No structured context: Claude saw a raw diff without understanding the relationships between files
No rules: impossible to reliably encode project conventions
No deduplication: the same findings came back in duplicates or triples
No cost control: a 2000-line diff could cost $15
No validation: no filter on false positives

CodeRift solves each of these problems. The structured pipeline (rules + AST + specialized agents + validation) produces more accurate findings than the "send the entire diff to an LLM and hope" approach.

Per-project configuration

Each project can customize the review via .coderift/context.md:

# Architecture

4 strict layers: rest, services, repositories, entities.
Violations to flag:
- rest importing repositories directly
- services doing raw SQL
- repositories containing business logic

# Frontend

API types in app/types/generated.ts are auto-generated.
Never manually redefine a type that exists in this file.

This file is injected into agent prompts as untrusted context (sandboxed, with no ability to alter review instructions). Agents use it to understand project conventions and flag specific violations.

The stack

CodeRift is built with the ecosystem I developed: IronFlow for workflow orchestration, the same layered architecture (entities/repositories/services/rest) as Netir, and MCP RTK optionally to reduce tokens on connected MCP servers. The Claude Code setup and skills I use daily served as the foundation for structuring CodeRift's review prompts.

Layered Architecture: Rust API with Axum, SQLx

Thomas Tartrau — Fri, 11 Sep 2026 16:54:18 +0000

Most Rust/Axum APIs I see on GitHub put everything in the same file: the handler extracts parameters, runs the SQL query, applies business logic, and returns JSON. That works for a demo project. On a production API with 30+ endpoints, state machines, SSE, JWT auth, and a worker lease system, it falls apart.

I structured IronFlow - a workflow engine where workflows are Rust code (see why I chose Rust for this project) - into strict layers spread across a 20-crate Cargo workspace. Dependencies only go in one direction: downward. A REST handler cannot call a SQL query directly, and an entity has no idea Axum exists.

This article shows this architecture with real code, the decisions that worked, and the ones I would reconsider.

The workspace structure

The Cargo workspace contains 20 crates. The main layers are:

ironflow-store/         # Entities + data access (traits + implementations)
  src/entities/         # Structs, enums, FSM
  src/postgres/         # PostgreSQL implementation (SQLx)
  src/memory/           # In-memory implementation (tests/dev)
ironflow-engine/        # Orchestration, execution, events
ironflow-api/           # Axum handlers, DTOs, middleware, OpenAPI
  src/entities/         # API DTOs (separate from store entities)
  src/routes/           # Handlers by domain
ironflow-core/          # AI providers, shell/HTTP/agent operations
ironflow-auth/          # JWT, authentication extractors
ironflow-types/         # Shared types (JSON envelopes)

Each layer is a separate crate in the workspace. The ironflow-api crate cannot access sqlx directly: it goes through the Store trait defined in ironflow-store.

Entities: the domain without a framework

The entities layer lives in ironflow-store/src/entities/. It defines domain types without depending on Axum or SQLx for queries. One file per concept: run.rs, step.rs, run_status.rs, step_status.rs, trigger_kind.rs.

The FSM in the type system

The core of IronFlow is a finite state machine (FSM) that manages the lifecycle of each run. Valid transitions are defined in an exhaustive matches!:

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum RunStatus {
    Pending,
    Running,
    Completed,
    Failed,
    Retrying,
    Cancelled,
    AwaitingApproval,
    Warning,
}

impl RunStatus {
    pub fn can_transition_to(&self, target: &RunStatus) -> bool {
        if self == target && self.is_terminal() {
            return true; // idempotent
        }
        matches!(
            (self, target),
            (RunStatus::Pending, RunStatus::Running)
                | (RunStatus::Pending, RunStatus::Cancelled)
                | (RunStatus::Running, RunStatus::Pending) // lease expired
                | (RunStatus::Running, RunStatus::Completed)
                | (RunStatus::Running, RunStatus::Failed)
                | (RunStatus::Running, RunStatus::Warning)
                | (RunStatus::Running, RunStatus::Retrying)
                | (RunStatus::Running, RunStatus::Cancelled)
                | (RunStatus::Running, RunStatus::AwaitingApproval)
                | (RunStatus::Retrying, RunStatus::Running)
                | (RunStatus::Retrying, RunStatus::Failed)
                | (RunStatus::Retrying, RunStatus::Cancelled)
                | (RunStatus::AwaitingApproval, RunStatus::Running)
                | (RunStatus::AwaitingApproval, RunStatus::Failed)
                | (RunStatus::AwaitingApproval, RunStatus::Cancelled)
        )
    }

    pub fn is_terminal(&self) -> bool {
        matches!(
            self,
            RunStatus::Completed | RunStatus::Failed
                | RunStatus::Warning | RunStatus::Cancelled
        )
    }
}

The matches! macro makes the transition table readable at a glance. Adding a transition means adding a line. Removing a state triggers a compiler warning everywhere it is used.

An important detail: terminal-to-same-terminal transitions are idempotent. A run that is already Failed receiving Failed is not an error. This simplifies concurrency scenarios between workers.

The generic `FsmState<T>`

For SQL-side transitions (via the lib_fsm library), IronFlow wraps the status with the state machine ID:

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
pub struct FsmState<T: Clone + Copy> {
    pub state: T,
    pub state_machine_id: Uuid,
}

Handlers pattern-match on run.status.state, while SQL queries use run.status.state_machine_id for atomic transitions. A single type carries both pieces of information.

The `Run` entity

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct Run {
    pub id: Uuid,
    pub workflow_name: String,
    pub status: FsmState<RunStatus>,
    pub trigger: TriggerKind,
    pub payload: Value,
    pub error: Option<String>,
    pub retry_count: u32,
    pub max_retries: u32,
    pub cost_usd: Decimal,
    pub duration_ms: u64,
    pub created_at: DateTime<Utc>,
    pub updated_at: DateTime<Utc>,
    pub started_at: Option<DateTime<Utc>>,
    pub completed_at: Option<DateTime<Utc>>,
    pub labels: HashMap<String, String>,
    pub scheduled_at: Option<DateTime<Utc>>,
    pub created_by: Option<RunActor>,
}

The Run is the store's internal model. The API never exposes it directly - it uses a RunResponse (DTO) that controls what goes out. IDs are UUID v7 (chronologically sorted, good for B-tree index performance).

The store: traits and two implementations

The store layer defines async traits for data access, with two implementations: PostgresStore for production and InMemoryStore for tests.

The `RunStore` trait

pub trait RunStore: Send + Sync {
    fn create_run(&self, req: NewRun) -> StoreFuture<'_, RunCreation>;

    fn get_run(&self, id: Uuid) -> StoreFuture<'_, Option<Run>>;

    fn list_runs(
        &self, filter: RunFilter, page: u32, per_page: u32
    ) -> StoreFuture<'_, Page<Run>>;

    fn update_run_status(
        &self, id: Uuid, new_status: RunStatus
    ) -> StoreFuture<'_, ()>;

    fn pick_next_pending(
        &self, lease: Option<LeaseRequest>
    ) -> StoreFuture<'_, Option<Run>>;

    fn reap_expired_leases(
        &self, limit: u32
    ) -> StoreFuture<'_, Vec<ReapedRun>>;

    // ... create_step, update_step, list_steps, get_stats, delete_run
}

StoreFuture<'a, T> is a Pin<Box<dyn Future<Output = Result<T, StoreError>> + Send + 'a>> - needed for object safety so the store can be used as Arc<dyn RunStore>.

The Store trait unifies all capabilities:

pub trait Store:
    RunStore + UserStore + ApiKeyStore + SecretStore
    + AuditLogStore + ArtifactStore + LogStore
{}

impl<T: RunStore + UserStore + ApiKeyStore + SecretStore
    + AuditLogStore + ArtifactStore + LogStore> Store for T {}

The blanket impl means any type that implements all 7 sub-traits is automatically a Store. Both InMemoryStore and PostgresStore implement all 7.

Two interchangeable backends

The PostgreSQL implementation uses SELECT FOR UPDATE SKIP LOCKED for concurrent run picking:

impl RunStore for PostgresStore {
    fn pick_next_pending(
        &self, lease: Option<LeaseRequest>
    ) -> StoreFuture<'_, Option<Run>> {
        Box::pin(async move {
            // SELECT FOR UPDATE SKIP LOCKED inside a transaction
            // Atomic transition Pending -> Running
        })
    }
}

The in-memory implementation uses an RwLock and a sorted Vec. Same API, same behavior, zero PostgreSQL required for tests:

let store: Arc<dyn Store> = Arc::new(InMemoryStore::new());
let run = store.create_run(NewRun {
    workflow_name: "deploy".to_string(),
    trigger: TriggerKind::Manual,
    payload: json!({}),
    max_retries: 3,
    // ...
}).await?.into_run();

The ironflow-api crate tests use InMemoryStore. No Docker, no migrations, no cleanup between tests. The PostgresStore has its own integration tests.

Store error handling

Store errors are storage errors, not HTTP errors:

#[derive(Debug, Error)]
pub enum StoreError {
    #[error("run not found: {0}")]
    RunNotFound(Uuid),

    #[error("step not found: {0}")]
    StepNotFound(Uuid),

    #[error("invalid status transition: {from} -> {to}")]
    InvalidTransition { from: RunStatus, to: RunStatus },

    #[error("lease lost on run {run_id}")]
    LeaseLost { run_id: Uuid, held_by: Option<String> },

    #[error("artifact {name:?} already exists on step {step_id}")]
    DuplicateArtifact { step_id: Uuid, name: String },

    #[error("database error: {0}")]
    Database(String),
}

The conversion to HTTP status codes happens in the API crate, not here. The store has no concept of a StatusCode.

The API layer: Axum handlers and DTOs

The ironflow-api crate assembles everything. It contains Axum handlers, response DTOs (separate from store entities), middleware, and OpenAPI documentation.

DTOs separate from entities

The API crate defines its own response types in src/entities/:

// ironflow-api/src/entities/run.rs - API DTO
#[derive(Debug, Serialize, Deserialize)]
pub struct RunResponse {
    pub id: Uuid,
    pub workflow_name: String,
    pub status: RunStatus,
    pub trigger: TriggerKind,
    pub error: Option<String>,
    pub cost_usd: Decimal,
    pub duration_ms: u64,
    pub created_at: DateTime<Utc>,
    pub created_by: Option<CreatedBy>,
    // ...
}

impl From<Run> for RunResponse {
    fn from(run: Run) -> Self {
        // Explicit conversion, controls what goes out
    }
}

RunResponse is the public contract. The store's Run is the internal model. The From<Run> conversion is the control point: you choose what is exposed and how.

A typical handler

#[utoipa::path(
    get,
    path = "/api/v1/runs/{id}",
    tags = ["runs"],
    params(("id" = Uuid, Path, description = "Run ID")),
    responses(
        (status = 200, body = RunDetailResponse),
        (status = 401),
        (status = 404),
    ),
    security(("Bearer" = []))
)]
pub async fn get_run(
    _auth: Authenticated,
    State(state): State<AppState>,
    Path(id): Path<Uuid>,
) -> Result<impl IntoResponse, ApiError> {
    let run = state.get_run_or_404(id).await?;

    let (steps, deps, artifacts) = join!(
        state.store.list_steps(id),
        state.store.list_step_dependencies(id),
        state.store.list_artifacts_for_run(id)
    );

    let response = RunDetailResponse {
        run: RunResponse::from(run),
        steps: steps?.into_iter().map(StepResponse::from).collect(),
        // ...
    };

    Ok(ok(response))
}

The handler does 3 things:

Verify authentication (Authenticated extractor)
Fetch data in parallel via tokio::join!
Convert to DTOs and return

The ? converts StoreError to ApiError via the From impl. Tracing is automatic. OpenAPI docs are generated by #[utoipa::path].

Error conversion

StoreError converts automatically to ApiError via #[from]:

#[derive(Debug, Error)]
pub enum ApiError {
    #[error("run not found")]
    RunNotFound(Uuid),

    #[error("authentication required")]
    Unauthorized,

    #[error("invalid credentials")]
    InvalidCredentials,

    #[error("{0}")]
    Conflict(String),

    #[error("database error")]
    Store(#[from] StoreError),
    // ...
}

impl IntoResponse for ApiError {
    fn into_response(self) -> Response {
        let status = match &self {
            ApiError::RunNotFound(_) => StatusCode::NOT_FOUND,
            ApiError::Unauthorized => StatusCode::UNAUTHORIZED,
            ApiError::Store(StoreError::LeaseLost { .. }) => StatusCode::CONFLICT,
            ApiError::Store(_) => StatusCode::INTERNAL_SERVER_ERROR,
            // ...
        };

        let envelope = ErrorEnvelope {
            code: self.code().to_string(),
            message: self.to_string(),
        };

        (status, Json(json!({ "error": envelope }))).into_response()
    }
}

Each StoreError is translated to a precise HTTP code. A LeaseLost is a 409 Conflict (the client can retry), not a 500. A RunNotFound is a 404. The store does not decide the HTTP code, the API does.

Router assembly

pub fn create_router(state: AppState, config: RouterConfig) -> Router {
    let internal_routes = Router::new()
        .route("/runs/next", get(pick_next_run))
        .route("/runs/{id}/status", put(update_run_status))
        .route("/runs/{id}/lease", post(renew_lease))
        .layer(from_fn(worker_token_auth));

    let api_v1 = Router::new()
        .route("/runs", get(list_runs).post(create_run))
        .route("/runs/{id}", get(get_run))
        .route("/runs/{id}/cancel", post(cancel_run))
        .route("/runs/{id}/approve", post(approve_run))
        .route("/workflows", get(list_workflows))
        .route("/stats", get(get_stats))
        .route("/events", get(events));

    Router::new()
        .nest("/api/v1/internal", internal_routes)
        .nest("/api/v1", api_v1)
        .layer(RequestBodyLimitLayer::new(2 * 1024 * 1024))
        .layer(from_fn(security_headers))
}

Two separate route groups: internal routes (worker-to-API, protected by a dedicated token) and public routes (JWT authentication). Internal routes use worker_token_auth, public routes use Authenticated. Both go through the same AppState.

AppState: dependency injection

#[derive(Clone)]
pub struct AppState {
    pub store: Arc<dyn Store>,
    pub engine: Arc<Engine>,
    pub jwt_config: Arc<JwtConfig>,
    pub worker_token: String,
}

The Arc<dyn Store> is the injection point. In production, it is a PostgresStore. In tests, it is an InMemoryStore. The handler does not know which one it uses.

Tests: the concrete benefit of the architecture

The get_run handler tests illustrate the benefit of traits:

#[tokio::test]
async fn existing_run() {
    let store = Arc::new(InMemoryStore::new());
    let run = store.create_run(NewRun {
        workflow_name: "test".to_string(),
        trigger: TriggerKind::Manual,
        payload: json!({}),
        max_retries: 3,
        // ...
    }).await.unwrap().into_run();

    let state = test_state_with_store(store);
    let app = Router::new()
        .route("/{id}", get(get_run))
        .with_state(state);

    let resp = app.oneshot(
        Request::get(format!("/{}", run.id))
            .header("authorization", auth_header)
            .body(Body::empty()).unwrap()
    ).await.unwrap();

    assert_eq!(resp.status(), StatusCode::OK);
}

No Docker, no database, no migrations. The test instantiates an InMemoryStore, creates a run, and verifies the handler returns 200. Execution takes a few milliseconds.

What works well

Store traits. Two interchangeable implementations (PostgresStore and InMemoryStore) simplify testing and allow starting the project without a database. The Arc<dyn Store> in AppState makes injection transparent.

DTOs separate from entities. The API's RunResponse and the store's Run are distinct types. Modifying the internal model does not break the API contract. The From<Run> conversion is the single control point.

End-to-end typed errors. From StoreError to ApiError, every conversion is explicit. The matches! in IntoResponse documents the error-to-HTTP-code mapping. No hidden .unwrap().

Generated OpenAPI documentation. utoipa annotates handlers and types. The spec is always in sync with the code. The embedded dashboard consumes this spec directly.

What I would change

The missing service layer. Today, business logic lives in handlers (for simple cases) or in the engine (for orchestration). An explicit ironflow-services crate with status transition logic, cost limit validation, and event construction would make handlers thinner and tests more targeted.

Boxed StoreFutures. The Pin<Box<dyn Future>> is needed for object safety of dyn RunStore, but adds one allocation per call. For non-dynamic usage (when the concrete type is known), direct async methods would be more performant. This is the classic flexibility vs. performance tradeoff.

The numbers

The IronFlow workspace:

Metric	Value
Crates in the workspace	20
REST endpoints (public + internal)	30+
Lines of Rust code	~25,000
Unit tests	150+
Store backends	2 (PostgreSQL + in-memory)
Supported AI providers	10

The project is open source on GitLab. The release profile uses lto = true, strip = true, codegen-units = 1, and panic = "abort". The resulting binary is compact and starts in under a second.

Conclusion

Layered architecture is not an invention. It is a classic pattern from Java/C#/.NET. What is specific to Rust is that the type system and Cargo workspaces make this separation enforced by the compiler, not by convention. A handler that tries to import sqlx directly will not compile if the ironflow-api crate does not list it in its dependencies.

The key point of IronFlow: store traits with two implementations. PostgresStore for production, InMemoryStore for tests. This is what makes handler tests fast and reliable without external infrastructure.

The cost is real: more crates, more From impls, more boilerplate for error conversions. But on a project with concurrent workers, leases, and state machines, the maintainability gains easily justify the investment.

If you are starting a Rust API with Axum, begin by separating entities from the rest. Add a store trait when you want to test without a database. Add DTOs when the internal model diverges from the API contract. And split into crates when compilation times or responsibility boundaries justify it.

To see how this architecture supports real use cases, read how IronFlow orchestrates AI agents for automated code review.

Why I Chose Rust for a Workflow Engine

Thomas Tartrau — Fri, 11 Sep 2026 16:54:14 +0000

Most workflow engines work the same way: define a step graph in a YAML file or DSL, let an engine interpret it, and hope the execution matches what you imagined. I used this approach for years with n8n, Airflow, and even Temporal in an earlier version, before hitting the limits of declarative definitions when business logic gets complex.

I built IronFlow to solve this. It's a workflow engine where workflows are imperative Rust code: no YAML, no DSL. The engine persists every step, tracks costs, and exposes everything through a REST API.

The problem with declarative workflows

A YAML workflow file works for simple cases: A then B then C. The trouble starts when you need:

Nested conditions: if step 2 fails and step 1 produced a certain flag, skip step 3 but run step 4 with different parameters
Conditional parallelism: fan-out on N items, but some items need different processing
Granular error handling: retry with backoff on some steps, fail-fast on others, structured logs for debugging

In YAML, these scenarios produce condition trees that become unreadable. You end up writing code in "hooks" or "scripts" embedded in the YAML, which is coding in a template language instead of a real one.

Temporal solved this by offering workflows as code (Go, Java, TypeScript, Python). Their approach is right. But Temporal requires heavy infrastructure: a cluster with Cassandra or MySQL, a frontend service, a history service, a matching service. For a project that needs to orchestrate AI agents and shell commands, it's overkill.

Why Rust and not Go or Node

The language choice for a workflow engine isn't neutral. The engine is an infrastructure component that runs continuously, manages concurrency, and manipulates state machines. Here's what motivated the Rust choice.

The type system for state machines

IronFlow's core is an FSM (finite state machine) managing each run's lifecycle. A run passes through precise states - Pending, Running, AwaitingApproval, Retrying, Completed, Failed, Cancelled - and transitions between these states are constrained.

In Rust, this constraint is expressed in the type system. The FSM rejects invalid transitions at compile time, not at runtime:

pub enum RunEvent {
    PickedUp,
    AllStepsCompleted,
    StepFailed,
    StepFailedRetryable,
    RetryStarted,
    MaxRetriesExceeded,
    CancelRequested,
    ApprovalRequested,
    Approved,
    Rejected,
}

Each event can only be applied from certain states. Approved is only valid from AwaitingApproval. PickedUp is only valid from Pending. The transition table is explicit in the code:

In Go, this same logic would use switch on string or int. An invalid transition error would only appear at runtime. In Node, you wouldn't even have guarantees on event types.

Tokio and zero-compromise parallelism

A workflow engine must handle concurrency everywhere: multiple runs in parallel, concurrent steps within a single run, pending HTTP calls, workers polling the API. Tokio provides all of this with near-metal performance.

IronFlow uses an API + workers model. The API owns persistence and never executes anything. Workers poll the API for pending runs, execute them locally, and stream steps and logs back. Scaling out means starting more workers.

Concretely, a workflow can fan-out on parallel steps with ctx.parallel():

let checks = ctx
    .parallel(
        vec![
            ("test", StepConfig::Shell(ShellConfig::new("cargo test"))),
            ("lint", StepConfig::Shell(ShellConfig::new("cargo clippy"))),
            ("audit", StepConfig::Shell(ShellConfig::new("cargo audit"))),
        ],
        true, // fail-fast: stop everything if one step fails
    )
    .await?;

Each step runs in its own Tokio task. The ? propagates errors naturally. No callback hell, no promise chaining.

A single binary, zero dependencies

Go also produces a static binary, and it's a common argument in its favor. But Rust goes further with lto = true, strip = true and codegen-units = 1 in the release profile: the binary is more compact and starts faster.

For IronFlow, this means trivial deployment: a single file to copy to the server. No Node runtime, no JVM, no Python with its virtualenvs. The worker runs with a few MB of RAM, even under load.

What Rust makes natural in IronFlow

Imperative code workflows

An IronFlow workflow is a WorkflowHandler trait implementation. You receive a WorkflowContext and chain operations:

struct Deploy;

impl WorkflowHandler for Deploy {
    fn name(&self) -> &str {
        "deploy"
    }

    fn execute<'a>(&'a self, ctx: &'a mut WorkflowContext) -> HandlerFuture<'a> {
        Box::pin(async move {
            ctx.shell("build", ShellConfig::new("cargo build --release"))
                .await?;

            let checks = ctx
                .parallel(
                    vec![
                        ("test", StepConfig::Shell(ShellConfig::new("cargo test"))),
                        ("lint", StepConfig::Shell(ShellConfig::new("cargo clippy"))),
                        ("audit", StepConfig::Shell(ShellConfig::new("cargo audit"))),
                    ],
                    true,
                )
                .await?;

            if checks.is_empty() {
                return Ok(());
            }

            ctx.approval("gate", ApprovalConfig::new("Ship to production?"))
                .await?;

            ctx.shell("deploy", ShellConfig::new("./deploy.sh")).await?;
            Ok(())
        })
    }
}

The control flow is standard Rust. If tests fail, ? propagates the error and the run transitions to Failed. The approval gate suspends the run until a human acts. No DSL to learn.

Interchangeable AI providers

IronFlow supports 10 AI providers, all behind the same AgentProvider trait. A workflow written for Claude runs on any other provider without modification:

let router = ProviderRouter::new(claude)
    .route(ProviderMatcher::ModelPrefix("nvidia/".into()), nvidia);

let a = Agent::new().prompt("Review").model(Model::SONNET).run(&router).await?;

let b = Agent::new().prompt("Review").model("nvidia/deepseek-v4-flash").run(&router).await?;

The ProviderRouter dispatches on the model name. A workflow can mix vendors within the same execution. Providers include Claude Code (local), SSH, Docker, Kubernetes (ephemeral and persistent), Anthropic API, OpenAI, Gemini, Mistral, and NVIDIA NIM.

In Go, this routing-by-trait pattern would use interfaces - similar on the surface, but without the lifetime guarantees Rust provides. In Node, you'd use duck typing and discover errors in production.

Architecture in 12 crates

The workspace is split into 12 crates, each with a clear responsibility:

Cargo's feature system lets you include only what you need. ironflow-core works as a standalone library without a server or database. Providers like SSH, Docker, and Kubernetes are behind feature flags (transport-ssh, transport-docker, transport-k8s).

Honest comparison with alternatives

	IronFlow	Temporal	Windmill	n8n
Definition	Imperative Rust code	Code (Go/Java/TS/Python)	Scripts (Python/TS/Go) + UI	GUI + JSON
Infrastructure	API + workers (Postgres)	Cluster (Cassandra/MySQL)	Server (Postgres)	Server (SQLite/Postgres)
Native AI agents	10 providers, built-in budgeting	No	No	Via plugins
Deployment	Single binary	Multi-service cluster	Docker	Docker
Language	Rust	Go (server) + multi-SDK	Rust (server)	Node.js

Temporal is the obvious choice for teams that need durable execution at scale and accept the operational complexity. Temporal actually chose Rust for their Core SDK, citing "fearless concurrency" and the fact that "if it compiles, it probably works."

Windmill chose Rust for its backend and reports 10 to 13x better performance than Airflow thanks to the PostgreSQL + Rust combination. Same stack as IronFlow.

n8n is perfect for no-code and quick automation, but its Node.js base and GUI model limit infrastructure use cases.

IronFlow sits between Temporal (too heavy for AI agent workflows) and no-code tools (too limited for complex logic). The bet is simple: if the workflow is complex enough to need conditions, loops, and granular error handling, it should be code. And if it's code, you should use a language that guarantees at compile time that states are correct.

What I'd do differently

Rust is not without trade-offs. Build time for a 12-crate workspace is significant - several minutes for a release build. And the Rust developer pool is smaller than Go's or TypeScript's.

If IronFlow were an internal enterprise tool with a 10-person team, Go would probably be a better choice. But for an open-source project where engine correctness is critical and performance matters, Rust is the right trade-off.

The code is open source

IronFlow is published under the MIT license on GitLab (mirror on GitHub). All crates are on crates.io. The project is part of a tooling ecosystem I'm building around automation and Claude Code, with MCP RTK (MCP filtering proxy) and the Claude Code skills I use daily. The complete setup tying all these tools together is detailed in a previous post. The project page has installation links and documentation. For a deep dive into the API's internal architecture (entities, store traits, Axum handlers), see Layered Architecture for a REST API in Rust with Axum and SQLx.

Writing effective Claude Code skills

Thomas Tartrau — Fri, 11 Sep 2026 16:54:10 +0000

Skills are the most underrated feature in Claude Code. I use dozens of them covering everything from Git commits to blog article creation. Most developers have none, or one or two copied from a tutorial.

This article shows how to write skills that work in production: the structure, the loading mechanism, the patterns I've identified after months of iteration, and the common mistakes.

What a skill is

A skill is a folder containing a SKILL.md file. The file combines a YAML frontmatter (metadata) and a Markdown body (instructions). When the user types /skill-name or phrases a request that matches the description, Claude loads the instructions and follows them. The official documentation covers installation and basic syntax.

commit-push/
  SKILL.md          # required: metadata + instructions
  references/       # optional: detailed docs
  scripts/          # optional: executable code
  assets/           # optional: templates, static files

The SKILL.md format is an open standard created by Anthropic and adopted by other agent products like Cursor. A skill written for Claude Code works as-is in these tools.

Progressive disclosure: why it matters

The loading mechanism is the most important aspect to understand. Without it, you write skills that are too large and waste context, or too vague and never trigger.

Loading happens in three levels:

Level 1 - Discovery (~100 tokens per skill). Only the name and description from the frontmatter are injected into the system prompt at the start of each session. Claude knows the skill exists and when it applies. Even with dozens of active skills, that's only a few thousand tokens - negligible in a 200K context.

Level 2 - Activation (<5,000 tokens). When the user's request matches a skill's description, Claude reads the full SKILL.md body. This is where the detailed instructions, step-by-step workflows, and checklists live.

Level 3 - Execution (on demand, unlimited size). The agent reads files from the references/ folder or runs scripts from scripts/ only when the Level 2 instructions tell it to. A blog skill might have 20 reference files, but Claude only loads 2 or 3 per execution.

The practical consequence: the SKILL.md body should stay under 5,000 tokens. Anything beyond that belongs in references/. If the skill is too large, Claude loads thousands of context tokens every activation, even when it only needs a fraction.

Anatomy of a SKILL.md

Here's the minimal structure:

---
name: my-skill
description: "|"
  What this skill does AND when to use it.
  Include trigger phrases in the languages your users speak.
---

# My Skill

## Workflow
1. First step
2. Second step
3. Third step

## Output format
What the user should receive in return.

The frontmatter: the routing contract

The frontmatter is the most critical component. The description is the only text Claude sees before deciding whether to activate the skill. If it's vague, the skill won't trigger.

Technical constraints:

name in lowercase with hyphens only, 1-64 characters
name must match the parent folder name exactly
Invalid YAML silently prevents loading - no error, the skill just disappears

Here's the description from one of my production skills:

name: commit-push
description: |
  Commit all changes with an auto-generated conventional commit message
  and push to remote, all in one step.
  Use when: "commit & push", "commit and push", "commit push",
  "/commit-push", "commit et pousse", "pousse ca", "fais un commit
  et push", "commit tout".

Three elements to note:

What it does - "commit all changes with auto-generated conventional commit message and push"
When to use it - explicit list of trigger phrases
Bilingual - triggers in both English and French

If I had only written "Commit and push changes", the skill would trigger on "commit and push" but not on "pousse ca" or "commit tout".

The body: keep it light

The SKILL.md body contains the workflow Claude should follow. Here's a simplified excerpt from my /lint-check skill:

# Lint Check

Run the full Rust lint pipeline and auto-fix errors.

## Workflow

1. Run `cargo fmt -- --check` to detect formatting issues
2. If formatting issues found, run `cargo fmt` to fix them
3. Run `cargo clippy -- -D warnings` to detect lint issues
4. If clippy issues found, fix them one by one
5. Run `cargo check` to verify compilation
6. If errors remain after 3 fix attempts, stop and report

## Error handling

| Scenario | Action |
|----------|--------|
| cargo fmt fails | Report the error, do not continue |
| clippy warns but compiles | Fix warnings, re-run |
| cargo check fails | Show the error, suggest a fix |

The skill is 30 lines, not 300. It says what to do, in what order, and how to handle errors. Claude doesn't need an explanation of what cargo clippy is - it already knows.

Two design philosophies

Pattern A: tool wrappers

The skill is a thin wrapper around a CLI or deterministic script. The logic lives in the code; the skill just orchestrates it.

Examples from my setup:

/lint-check orchestrates cargo fmt, cargo clippy, cargo check
/commit-push orchestrates git status, git diff, git log, git add, git commit, git push
/seo-scan orchestrates an SEO crawler and updates a tracking file

MCP RTK is a good example of this pattern: the skill orchestrates a token filtering proxy via CLI commands, with no logic in prose.

Pattern B: cognitive disciplines

The skill encodes a methodology the agent must follow. It's pure prompt engineering - no script to run, just a thinking process.

Examples:

/systematic-debugging enforces a 5-step debugging methodology (reproduce, isolate, hypothesize, verify, fix)
/security-audit defines an OWASP top 10 checklist with patterns to search by category

Pattern B is harder to write well. The temptation is to over-explain. Claude knows how to debug - the skill adds structure to the process, not knowledge.

Patterns for effective skills

After months of iterating, here are the patterns that work.

Bash first, prose second

A code block the agent can execute beats a paragraph describing what to do.

Bad:

Check if there are uncommitted modified files in the current
git repository by using the git status command.

Good:

1. Run `git status` to check for uncommitted changes

Claude knows what git status does. The short version is clearer and more reliable.

State-check before action

Always verify the current state before modifying anything. Without this, Claude acts on assumptions and breaks things.

## Workflow
1. Run `git status` to verify clean working tree
2. Run `git log --oneline -5` to confirm current branch
3. Only then: create the feature branch

Validation loops

After each action, verify the result is correct before moving to the next. My /dev-pipeline skill does this at every step:

4. Run `cargo clippy -- -D warnings`
5. If clippy reports errors:
   a. Fix the errors
   b. Re-run clippy
   c. If errors persist after 3 attempts, stop and report
6. Only if clippy passes: proceed to tests

Without validation loops, Claude chains steps even when one fails. It ends up "completing" a pipeline where every step has failed.

Compose primitives

Don't bundle entire workflows into a single skill. Compose simple skills together.

My /dev-pipeline skill doesn't reimplement linting - it calls /lint-check. It doesn't reimplement commits - it calls /commit-push. Each skill does one thing, and workflows compose these primitives.

# Dev Pipeline

1. Plan the implementation (use EnterPlanMode)
2. Implement the changes
3. Run `/lint-check` to verify code quality
4. Run tests
5. Run `/commit-push` to commit and push

Document output formats

The agent must know exactly what it produces. Without an output specification, Claude improvises a different format every execution.

## Output format

Deliver a summary with:
- Files modified: list of paths
- Tests: pass/fail count
- Lint: pass/fail with details
- Commit: the conventional commit message used

Anti-patterns

Don't re-teach what the model knows

# Bad
JSON (JavaScript Object Notation) is a structured data format
used for data exchange...

# Good
Generate a JSON response matching the schema in references/schema.md.

Claude knows what JSON is. Every token wasted on unnecessary pedagogy is a context token lost.

Don't write vague descriptions

# Bad - will almost never trigger
name: helper
description: Helps with dev stuff

# Good - clear and specific triggers
name: lint-check
description: |
  Run the full Rust lint pipeline (cargo fmt, clippy, check)
  and auto-fix errors. Trigger on: "lint check", "lance le lint",
  "cargo fmt && cargo clippy", "check my Rust code".

A vague description means Claude doesn't know when to activate the skill. It has dozens of descriptions to compare against the user's request - precision is essential.

Don't create monolithic mega-skills

One skill = one capability. If the description contains "and" between two independent actions, it's probably two skills.

My first /dev-pipeline was 500 lines with everything inline: linting, tests, review, commit, push, MR creation. Today it's 40 lines and composes five specialized skills.

Don't ignore failure modes

Document what can go wrong and how to react. Without this, Claude stops or invents a solution when a command fails.

## Error handling

| Scenario | Action |
|----------|--------|
| No git remote configured | Stop, ask user to configure |
| Pre-commit hook fails | Fix the issue, retry once |
| Push rejected (not fast-forward) | Run `git pull --rebase`, retry |
| Merge conflict after rebase | Stop, show conflicts to user |

Don't use absolute paths

# Bad
Read /Users/thomas/.claude/scripts/validate.py

# Good
Read scripts/validate.py from the skill directory

Absolute paths break when the skill is shared or used on another machine. Paths relative to the skill directory or environment variables are portable.

Project-specific skills

The most powerful skills are those adapted to a specific project. In my setup, the Netir project has six skills that encode the project's conventions:

# netir-cpm/SKILL.md (excerpt)
name: netir-cpm
description: |
  Commit, push and create a GitLab Merge Request for the Netir
  project. Netir conventions applied: assignee ThomasTartrau,
  reviewer netir-bot, label "MR::en attente de review".
  Use when: "/cpm", "create the MR", "commit push mr".

The difference from the generic /cpm: Netir conventions (labels, reviewer, assignee) are hardcoded. I don't need to re-specify them for every MR.

Another example: /netir-qa-swarm launches four review agents in parallel, each with a different focus:

## Agents

| Agent | Focus |
|-------|-------|
| Architecture | Layers, separation of concerns |
| Security | OWASP, injections, auth, rate limiting |
| Rust quality | Idioms, clippy, performance, unwrap |
| Business patterns | Domain coherence, naming, edge cases |

Each agent has instructions specific to the Netir codebase (the Axum/SQLx stack, naming conventions, error patterns). A generic review skill doesn't know these conventions.

Testing a skill

The most important test: invoke the skill with varied phrasings and verify it triggers.

Users don't say "/invoke-my-skill". They say:

"commit and push"
"run the linter"
"create a MR"
"check the code"

If these natural phrasings don't trigger the skill, the description needs work. I add failing phrasings to the frontmatter triggers.

The second test: verify the instructions produce the expected result on a real case. No imaginary dry-run - run the skill on an actual project and check the output.

Checklist before publishing a skill

Before deploying a new skill to my configuration repo:

The name matches the folder name exactly
The description includes triggers in French and English
The SKILL.md body is under 5,000 tokens
Details are in references/, not the body
Failure modes are documented
Output format is specified
No secrets, tokens or absolute paths in the skill
Destructive commands are protected by confirmations
The skill has been tested with at least 3 different phrasings

What I've learned

The description is the router. Invest as much time on the description as on the body. A skill with perfect instructions but a vague description will never trigger.

Code beats prose. A deterministic script is always more reliable than ambiguous instructions. If a task has a single correct answer, put the logic in a script, not in Markdown.

The cheapest context is context you don't load. Progressive disclosure exists for a reason. A 200-line skill that could be 40 with references wastes context on every activation.

Test with real phrasings. Users don't type clean commands. They write "commit this", "push it", "lint" - triggers must cover these variants.

Skills transform Claude Code from a generic assistant into a tool adapted to your specific workflow. The projects page lists the other tools I've built around this ecosystem.

MCP RTK: cut 90% of MCP server tokens

Thomas Tartrau — Fri, 11 Sep 2026 16:54:06 +0000

I use Claude Code every day for development. Like many developers, I've connected several MCP servers (GitLab, Grafana, Sentry...) to give Claude direct access to my tools. The problem: every MCP call injects tens of thousands of tokens into the context, and the bill spirals fast.

I built MCP RTK to fix this. It's an MCP proxy written in Rust that sits between Claude Code and MCP servers, filtering responses before they reach the model. Result: over 267 million tokens saved across my 38,000+ commands.

The problem: oversized MCP responses

The MCP protocol (Model Context Protocol) lets Claude interact with external tools. When Claude calls an MCP tool, the server returns a JSON response. The issue is that these responses often contain:

empty or null fields that add nothing
technical metadata (internal timestamps, pagination IDs, HTTP headers)
very long values (full logs, HTML descriptions, entire diffs)
arrays with dozens of entries when 5 would suffice

A single list_issues call on GitLab can consume over 180,000 tokens. Claude only needs a fraction to answer the question. The rest is pure waste.

Over a typical work session with 50 to 100 MCP calls, that easily adds up to 500,000 wasted tokens injected into the context.

The solution: an 8-step filtering proxy

MCP RTK sits transparently between Claude Code and MCP servers. No workflow change needed: Claude keeps calling the same tools, but responses pass through a filtering pipeline before reaching the context.

The pipeline has 8 steps:

Remove null and empty fields - fields without values are stripped
Truncate long strings - values exceeding a configurable threshold are cut
Field whitelist - only useful fields are kept
Field blacklist - known useless fields are removed
Deduplication - identical entries are merged
Array compression - long arrays are sampled
Technical metadata removal - API-internal fields are stripped
Normalization - output format is standardized

Each step is independently configurable. You can enable or disable each filter, adjust thresholds, and define server-specific rules.

Configuration with presets

Configuration uses a TOML file. MCP RTK ships with community presets for popular servers:

[servers.gitlab]
preset = "gitlab"

[servers.grafana]
preset = "grafana"

[servers.sentry]
preset = "sentry"

Each preset defines which fields to keep, which to exclude, and appropriate truncation thresholds for the server. For custom servers, you define rules directly:

[servers.my-api]
whitelist = ["id", "name", "status", "created_at"]
max_string_length = 500
max_array_length = 10

MCP RTK auto-detects installed MCP servers and offers to configure them.

Results

Across my 38,000+ commands, MCP RTK has saved 267 million tokens with an average reduction rate of 87%. On Opus 4.6 ($15/M input tokens), that's roughly $4,000 in savings:

Useful information is preserved. Claude responds with the same accuracy, but consumes far fewer tokens per session. The mcp-rtk gain command lets you track savings in real time:

Tokens saved:      267.1M (86.7%)
Efficiency meter: █████████████████████░░░ 86.7%

Installation

MCP RTK is distributed as a single binary:

cargo install mcp-rtk

One line change in your Claude Code config - wrap the existing MCP command with mcp-rtk --:

{
  "mcpServers": {
    "gitlab": {
      "command": "mcp-rtk",
      "args": ["--", "npx", "-y", "@nicepkg/gitlab-mcp"],
      "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-..." }
    }
  }
}

MCP RTK detects the upstream server from the command and loads the matching preset automatically.

Why Rust?

Rust was a deliberate choice. The proxy must process every MCP response with minimal latency to avoid slowing down the workflow. Rust provides:

near-instant startup (no JVM, no runtime)
minimal memory footprint (a few MB)
a single binary with no dependencies to install
compile-time memory safety guarantees

The code is open source

MCP RTK is published under the MIT license on GitLab (mirror on GitHub). Community presets are maintained by users: anyone can contribute their own configurations for new MCP servers.

The project is part of a tooling ecosystem I'm building around Claude Code, alongside Skill Radar (detecting repetitive patterns in sessions) and Claude Deck (multi-workspace for parallel sessions). To learn how to write your own skills, see the guide on effective skills. The project page has installation links and documentation.

My Claude Code setup in 2026

Thomas Tartrau — Fri, 11 Sep 2026 16:44:18 +0000

I've been using Claude Code as my primary development tool since early 2025. After hundreds of sessions on Rust, TypeScript and React projects, I've built a configuration that evolves every week. This article shows the setup as it is today, with real files.

The structure: where config lives

Everything starts from ~/.claude/. That's Claude Code's global directory. Here's how mine is organized:

~/.claude/
  CLAUDE.md              # global instructions
  settings.json          # model, hooks, permissions, skill overrides
  RTK.md                 # MCP RTK reference (loaded via @RTK.md)
  agents/
    netir-reviewer/      # custom Rust review agent
  skills/                # symlinks to the config repo
    blog -> .../global/skills/blog/
    commit-push -> .../global/skills/commit-push/
    netir-cpm -> .../projects/netir/skills/netir-cpm/
    ...

The trick: skills are symlinks to a Git configuration repo that I maintain separately. This lets me version, sync across machines, and separate global skills from project-specific ones.

CLAUDE.md: the most important file

The global CLAUDE.md is loaded into every session. This is where I put rules that apply everywhere, regardless of the project.

Mine is under 30 lines. Each line was added after a real problem:

## French language -- Strict orthography
- Always respond in French with all correct diacritical marks.
- FORBIDDEN to write without accents.

- Never launch subagents or delegate tasks unless the user explicitly asks.
- Output code first, explanation after - only if non-obvious.
- No compliments or affirmations in code reviews. State the issue, show the fix, stop.
- No em dashes, smart quotes, or decorative Unicode.

## Git & GitLab
- Simple feature branch workflow: feature branches merge into main.
- Always use conventional commit messages.

@RTK.md

A few key points:

The language rule comes first because without it, Claude switches to English or drops accents after context compaction.
"Never launch subagents unless asked" prevents Claude from delegating to sub-agents when it's unnecessary. Without this rule, it spawns agents for simple searches and wastes context.
@RTK.md is a reference to a separate file documenting RTK commands. Claude loads it automatically when it needs the context.

Rules: contextual instructions

Rules are Markdown files in ~/.claude/rules/ (or in the config repo). The difference from CLAUDE.md: they have a paths header that activates them only on matching files.

I have 15. Here are the most useful ones:

Code discipline

---
paths: "**/*.{rs,ts,tsx,jsx,js,sql,toml}"
---

# Code discipline

## Prior art - search before writing
Before writing a helper or abstraction: grep 2-3 variants
of the concept. If an equivalent exists, reuse it.

This rule activates on all code files. It prevents Claude from recreating utilities that already exist in the project.

Security

---
paths: "**/*.{rs,ts,tsx,sql,toml,yml,yaml},**/Dockerfile"
---

- Secrets: never hardcoded. Use env vars or vault.
- Injections - zero tolerance: Always use parameterized queries.
- JWT stateless by default. Short-lived access + long-lived refresh.
- HTTP security headers: CORS, X-Content-Type-Options, HSTS, CSP.

Anti "fake done"

# Agent Verification -- 11 "Fake Done" Shortcuts

Before marking any task as complete, verify the diff against each shortcut.
If any applies, the task is NOT done.

1. Relaxed tests - assertions weakened to make red go green
2. Swallowed errors - try/catch that hides the failure
3. Stub returns - hardcoded return values
4. Comment-as-fix - the bug is now a TODO
5. Happy-path only - 500s, empty inputs unhandled
...

This one is agent-specific. When Claude marks a task as done, it must check its own diff against these 11 patterns. It catches cases where the code compiles but doesn't solve the actual problem.

Other rules cover: Rust imports, layered architecture, database migrations, JavaScript/TypeScript pitfalls, performance, refactoring, SQLx compile-time checks, and testing.

Skills: custom slash commands

Skills are SKILL.md files in folders under ~/.claude/skills/. Each skill defines a slash command (e.g., /commit-push) with detailed instructions.

I have 55 skills installed with 40 active (15 disabled via skillOverrides in settings.json). They fall into three categories:

Daily workflow skills

/commit-push - auto-generated conventional commit message + push in one command
/cpm - commit, push and GitLab Merge Request creation in one command
/dev-pipeline - plan, implement, lint, test, review, ship - the full pipeline
/lint-check - cargo fmt && cargo clippy && cargo check with auto-fix
/work-on-issue - fetch a GitLab issue, assign, plan, implement, test, verify

Review and quality skills

/security-audit - OWASP top 10 audit on the codebase
/systematic-debugging - structured debugging methodology
/netir-qa-swarm - 4 reviewers in parallel on a MR (architecture, security, Rust quality, business patterns)
/netir-review-triage - sorts review comments into actionable/nit/ambiguous

Content skills

/blog - complete article creation pipeline (research, writing, SEO, scoring)
/linkedin-post-coach - interactive coaching for LinkedIn posts
/useful-for-me - analyzes an external repo/tool and tells me if it's useful for my projects

Project-specific skills

The Netir setup illustrates project-specific skills well. These skills live in projects/netir/skills/ and only activate inside the Netir directory:

netir-cpm          # CPM with Netir conventions (labels, reviewer)
netir-qa-swarm     # multi-agent review
netir-review-triage # review sorting
netir-alert-triage # monitoring alert triage
netir-tech-debt    # tech debt analysis
netir-next         # next task selection

A skill is just a Markdown file with instructions. Here's a simplified excerpt of /commit-push:

# Commit & Push

1. git status to see modified files
2. git diff to analyze changes
3. git log -5 for existing commit style
4. Generate a conventional message (feat/fix/refactor...)
5. git add relevant files
6. git commit
7. git push

The power comes from composition: /dev-pipeline internally calls /lint-check, then chains with review and commit.

Disabling unused skills

The 15 disabled skills are set in settings.json:

{
  "skillOverrides": {
    "cost-estimate": "off",
    "email-campaigns": "off",
    "tdd": "off",
    "teach": "off"
  }
}

This avoids cluttering autocompletion and prevents Claude from invoking them accidentally.

Hooks: automate without thinking

Hooks are shell commands executed automatically on certain events. The most important one in my setup:

The RTK integration

RTK (Rust Token Killer) is an open source tool that integrates with Claude Code via a PreToolUse hook. It intercepts Bash commands and filters outputs to reduce token consumption.

The configuration is a single entry in settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "rtk hook claude"
          }
        ]
      }
    ]
  }
}

RTK runs before every Bash command. It intercepts CLI commands (git status, find, grep, ps aux...) and rewrites them to go through its filtering proxy. Result: CLI outputs are filtered automatically, without Claude or me having to think about it.

The numbers on my current setup:

Total commands:    39,646
Tokens saved:      276.4M (86.8%)
Top commands:
  rtk read    3,067 calls   217.8M tokens saved
  rtk grep    5,408 calls    13.8M tokens saved
  rtk find      573 calls    11.8M tokens saved

On Opus ($15/M tokens for input), 276 million tokens saved represents roughly $4,100 in savings. The hook pays for itself in the first session.

I also built MCP RTK, a complementary proxy that applies the same filtering principle to MCP server responses (GitLab, Grafana, Sentry...).

Custom agents

Agents are files in ~/.claude/agents/. They define a specialized profile with restricted tools.

I have a single custom agent: netir-reviewer, a Rust code reviewer specific to the Netir project. It checks layered architecture, SQLx conventions, error handling, imports, OpenAPI registration, and tracing.

The difference between a skill and an agent: a skill gives instructions to the main session, an agent is a separate session with its own context and tools. A review agent only has access to Read and Grep, not Edit or Write - it can't modify code, only read it and flag issues.

The configuration repo

This entire setup is managed in a private Git repo:

~/Documents/dev/claude/personal-config/
  install.sh           # setup script (symlinks, copies)
  global/
    CLAUDE.md           # global instructions
    rules/              # 15 rule files
    skills/             # global skills (blog, commit-push, etc.)
  projects/
    _template/          # template for new projects
    netir/              # Netir-specific config
      agents/
      rules/
      skills/
    jarvis/             # Jarvis-specific config

install.sh creates symlinks from ~/.claude/skills/ to the repo. When I add a skill or modify a rule, a git pull on another machine is enough to sync.

The project template

The _template/ folder contains a base structure for starting a new project with Claude Code:

cp -r projects/_template projects/my-new-project
# Adapt rules and skills to the project
./install.sh

What I've learned

After months of iterating on this config:

Keep CLAUDE.md short. Early versions were 200+ lines. Claude would skim them and forget rules. Under 30 well-chosen lines are more effective than an exhaustive document.

Contextual rules beat a big CLAUDE.md. Loading Rust rules only on .rs files saves context and avoids confusion between languages.

Disable unused skills. 55 skills is too many. The 15 disabled ones don't serve my current workflows. Keeping them active slows autocompletion and adds noise.

A single well-placed hook is enough. The RTK hook on PreToolUse covers 90% of optimization needs. No need for complex hooks on every event.

Version your config. A Git repo for Claude Code config seems overkill at first. In practice, it lets you roll back when a change breaks something, and sync between machines without friction.

The setup keeps evolving. Every repeated friction in a Claude Code session becomes a candidate for a new rule, a new skill, or a hook adjustment. To go further: my guide on writing effective skills details the patterns and anti-patterns, and the projects page lists the other tools I've built around this ecosystem.

DEV Community: Thomas Tartrau

JSON vs Programmatic Tool Calling with Claude

The problem: round trips

Approach 1: JSON schema + manual loop

Approach 2: Tool Runner SDK

Approach 3: programmatic tool calling

Comparison

When to use what

In practice

Automated code review with CodeRift

The architecture

The 7-step review pipeline

Steps 1-3: Preparation

Step 4: The review pipeline (the core)

Steps 5-6: Publishing

Step 7: Commit status

Findings

Why not just call Claude Code?

Per-project configuration

The stack

Layered Architecture: Rust API with Axum, SQLx

The workspace structure

Entities: the domain without a framework

The FSM in the type system

The generic FsmState<T>

The Run entity

The store: traits and two implementations

The RunStore trait

Two interchangeable backends

Store error handling

The API layer: Axum handlers and DTOs

DTOs separate from entities

A typical handler

Error conversion

Router assembly

AppState: dependency injection

Tests: the concrete benefit of the architecture

What works well

What I would change

The numbers

Conclusion

Why I Chose Rust for a Workflow Engine

The problem with declarative workflows

Why Rust and not Go or Node

The type system for state machines

Tokio and zero-compromise parallelism

A single binary, zero dependencies

What Rust makes natural in IronFlow

Imperative code workflows

Interchangeable AI providers

Architecture in 12 crates

Honest comparison with alternatives

What I'd do differently

The code is open source

Writing effective Claude Code skills

What a skill is

Progressive disclosure: why it matters

Anatomy of a SKILL.md

The frontmatter: the routing contract

The body: keep it light

Two design philosophies

Pattern A: tool wrappers

Pattern B: cognitive disciplines

Patterns for effective skills

Bash first, prose second

State-check before action

Validation loops

Compose primitives

Document output formats

Anti-patterns

Don't re-teach what the model knows

Don't write vague descriptions

Don't create monolithic mega-skills

Don't ignore failure modes

Don't use absolute paths

Project-specific skills

Testing a skill

Checklist before publishing a skill

What I've learned

MCP RTK: cut 90% of MCP server tokens

The generic `FsmState<T>`

The `Run` entity

The `RunStore` trait