DEV Community: Waruna

I Turned Claude Code Into a Dev Team With One File

Waruna — Wed, 08 Apr 2026 15:05:02 +0000

Most people drop a few rules into their CLAUDE.md and call it a day. I built an entire engineering workflow — a Tech Lead, specialist agents, a senior code reviewer, and a validation pipeline — all orchestrated from a single global file sitting in ~/.claude/CLAUDE.md.

Here's how I got there, and why it changed how I work with Claude Code.

The Problem: Claude Code Is a Brilliant Intern

Out of the box, Claude Code is smart but unsupervised. It'll jump straight into implementing something without asking clarifying questions. It'll say "done" without compiling. It'll delete a file it shouldn't have touched. It'll assume what you meant instead of asking what you meant.

Sound familiar?

These aren't Claude Code problems — they're process problems. And they're the exact same problems you'd have with a junior developer who has no engineering lead, no code review, and no CI pipeline.

So I gave Claude Code all three.

Global vs Project: The Right Separation

Before I walk through the file, one important design decision: I keep two layers of CLAUDE.md.

Global (~/.claude/CLAUDE.md) defines how work gets done — the process, the roles, the rules. It applies to everything.

Project-level (project-root/CLAUDE.md) defines what we're working with — the tech stack, naming conventions, file structure, dependencies. It's specific to each codebase.

This separation means my workflow stays consistent whether I'm working on a SwiftUI app, a Rails backend, or a Next.js frontend. The process doesn't change. Only the context does.

The Pipeline

Here's the core idea: every task flows through a pipeline, just like it would on a real engineering team.

User Task
    → Tech Lead Orchestrator (analyze, route, spec)
        → Specialist Agent (implement)
            → Senior Code Reviewer (review, loop until clean)
                → Validation (build, compile, test — prove it works)
                    → Delivery

No shortcuts on quality. Every path goes through review and validation. Let me break down each piece.

1. The Tech Lead Orchestrator

Every task starts here. No agent works independently without a brief from the Tech Lead. This is the single most important rule in the file, and it solves the "Claude just started coding before understanding the task" problem.

The Tech Lead's job:

Read the project's CLAUDE.md before doing anything (context loading)
Analyze the task and determine complexity
Clarify ambiguities with the user before assigning work
Route appropriately — trivial tasks get a fast track, complex ones get a full spec

That context loading step is subtle but critical. Without it, Claude will carry assumptions from a previous task into a new one. Explicitly telling it to re-read the project file at the start of every task prevents drift.

2. Fast-Track vs Full Path

Not every task needs the same ceremony. A typo fix shouldn't go through the same process as a new feature.

Fast-track is for trivial changes — single-file fixes, formatting, config tweaks, simple renames. The Tech Lead assigns directly to a specialist with a lightweight brief instead of a full spec.

Full path is for everything else. The Tech Lead writes a detailed spec with acceptance criteria, relevant file paths, and clear deliverables.

Here's the key: fast-track skips the detailed spec, not the review. Both paths converge at the same Senior Code Reviewer and Validation gates. Nothing ships unreviewed, regardless of how simple it seems.

This was a deliberate choice. I've been bitten too many times by "trivial" changes that introduced regressions. Even a one-liner deserves a second pair of eyes.

3. The Senior Code Reviewer

This is where quality gets enforced. Every change, from every path, passes through the Senior Code Reviewer before it reaches the user.

The reviewer checks against:

Project standards and the project-level CLAUDE.md
Bugs, edge cases, and security issues
A severity classification: critical (blocker), warning (should fix), nit (optional)

If there are concerns, the work goes back to the specialist with specific feedback. This loops until the reviewer passes with no concerns. No critical issues means the code moves to validation.

The review loop is what turns Claude Code from "generate and hope" into "generate and verify." It's the difference between code that looks right and code that is right.

4. Validation: Prove It Works

This is the piece most CLAUDE.md files miss entirely. Claude will happily tell you "the implementation is complete" without ever running the code. That's not good enough.

After review passes, the code must be validated using the appropriate method for the project:

Swift/iOS → xcodebuild, run in iOS Simulator
Android → Gradle build, run in Android Emulator
Web (JS/TS) → npm run build or yarn build
Web (Rails) → bundle exec rails test
Browser UI → Playwright end-to-end tests
CLI tools → Run the command, verify output
Libraries → Run the test suite (pytest, rspec, jest, etc.)

If validation fails, it loops back to the specialist with the actual errors. No task is considered done until it has been proven working.

This single addition — "compile it, build it, run it" — eliminated an entire class of bugs I used to catch manually after delivery.

5. The Safety Rails

Beyond the pipeline, I have a few rules that apply globally across all agents.

The Golden Rule

NEVER ASSUME. ALWAYS ASK.

If requirements are unclear, ambiguous, or incomplete: stop work, list specific questions, wait for clarification. This applies to every agent at every stage.

It sounds obvious, but without this rule, Claude will fill in the blanks with assumptions — and those assumptions are often wrong. Especially in agentic loops where one bad assumption compounds through the entire pipeline.

Destructive Actions

Certain operations require explicit user confirmation:

Deleting files or directories
Renaming files that are imported elsewhere
Large-scale refactors across multiple files
Removing or replacing dependencies
Dropping database tables or destructive migrations

I learned this the hard way. Claude is fast. Sometimes too fast. A confirmation gate on irreversible actions gives you a chance to catch mistakes before they happen.

Iteration Limit

Maximum 3 revision cycles across review and validation combined. If the issue isn't resolved after 3 loops, the Tech Lead escalates to the user with a summary of what's blocking progress. This prevents infinite loops where Claude keeps trying and failing to fix the same issue.

6. Standardized Communication

When you have multiple agents handing off work to each other, the format of those handoffs matters. I standardized it:

Tech Lead → Specialist: Task description, acceptance criteria as a checklist, relevant file paths.
Specialist → Reviewer: Summary of changes, files modified, trade-offs or decisions made.
Reviewer → Tech Lead: Critical issues (blockers), warnings (should fix), nits (optional). Clear pass/fail.

This isn't glamorous, but it prevents a lot of wasted cycles. When the reviewer gets a change with no context about what was intended, the review quality drops. When the specialist gets vague feedback like "needs improvement," they guess — and usually guess wrong.

The Meta Moment

Here's the part that made me smile: I built this file with Claude. I started with my original version, asked Claude to critique it, iterated on the suggestions, and refined the result through conversation.

Claude reviewed its own operating instructions, found gaps, and helped fix them. If that's not eating your own dog food, I don't know what is.

What Changed in Practice

Since adopting this workflow:

Fewer "it's done" surprises. The validation step catches compilation errors and test failures before I ever see the output.
Clearer communication. When Claude asks me a clarifying question instead of assuming, it saves 10 minutes of undoing wrong assumptions.
Consistent quality across projects. Whether I'm in a Swift codebase or a Rails app, the process is the same. Only the project-level context changes.
Less babysitting. The review loop catches issues I would have caught manually in a second pass. Now I spend that time on higher-level decisions.

Try It Yourself

The full file lives in ~/.claude/CLAUDE.md. That's the global config — it applies to every project you work on with Claude Code.

For project-specific rules (tech stack, naming conventions, file structure), create a CLAUDE.md in your project root. The global file handles the how, the project file handles the what.

Start with the pieces that solve your biggest pain points. If Claude keeps assuming instead of asking, add the Golden Rule. If you're tired of "done" without proof, add the Validation step. If changes keep shipping with bugs, add the Review loop.

You don't need the whole pipeline on day one. But once you have it, you won't go back to working without it.

If you're using Claude Code and want to see the complete CLAUDE.md file, drop a comment — happy to share the full thing.

I built a real-time F1 race replay and live timing app — here's how

Waruna — Thu, 26 Feb 2026 11:15:30 +0000

I'm a massive F1 fan. And like most F1 fans, I've always been frustrated by the TV coverage — you only ever see what the director wants you to see. What's happening with the midfield battle? Where exactly is everyone on track right now?

So I built Race Telemetry.

It's a web app that lets you replay any F1 race — all 20 cars, moving around the actual circuit in real time, exactly as it happened. Think of it like one of those scale electric race sets, but for real F1 data. You can also follow live car positions during a Grand Prix as it's happening.

What it does

Race replay — pick any race from 2024 or 2025, hit play, and watch every car move around the real circuit layout
Live timing — during a live race, track where every car actually is on track (not just the standings)
Analytics — dig into lap data, position changes, and strategy

The tech stack

Frontend

Next.js 15 (App Router) + React 19 + TypeScript
Tailwind CSS v4 + Framer Motion for animations
Canvas for the track map (much better than SVG for 20 moving dots with GPS data)

Backend

FastAPI (Python) with async httpx
File-based JSON cache to avoid hammering the API
OpenF1 API for all race data (real GPS coordinates, lap times, positions)

Data

The hardest part was figuring out car positions. The OpenF1 API gives you GPS coordinates for each car, but interpolating that into smooth, accurate replay required some work. I ended up using cumulative lap time to compute positions rather than relying on the position endpoint alone, with a fallback for edge cases.

Another tricky bit — OAuth2 token handling with OpenF1. It returns expires_in as a string, not an integer. Took me longer than I'd like to admit to figure that out.

The track map

One of the things I'm most happy with is the track map. It uses actual GPS circuit outlines from the OpenF1 Location API — not a simplified oval or SVG approximation. Every circuit is rendered from real coordinate data, which means the Monaco hairpin looks like the Monaco hairpin.

Rendering is done on Canvas rather than SVG or DOM elements. With 20 cars updating every fraction of a second, Canvas is significantly faster and the animation stays smooth.

What's next

iOS mobile app
Deeper analytics (tire strategy, gap charts, sector times)

Try it

It's live now at https://www.racetelemetry.com — no signup, just pick a race and go.

Would love feedback from other devs and F1 fans. What would you want to see next?

Ruby on Rails - Calculating pricing based user's purchasing power parity

Waruna — Fri, 10 Jan 2025 18:12:29 +0000

Recently, I published a simple ruby gem for calculating pricing for digital products based on the user's purchasing power parity.

Not everyone can afford the default pricing of the high-income world. A cup of Coffee in India or Argentina costs less than in the USA or Singapore. Therefore, I wanted to apply the same principle to a digital product I'm building. I couldn't find an easy way to calculate this with Ruby. Looking around, I got inspired by an NPM package called purchasing-power-parity npm and created a similar library using Ruby.

If you would like to take a look at the source code or would like to contribute here in the link to Github repo.

https://github.com/warunacds/geo_ppp

Library is pretty simple to use. Add this line to your application's Gemfile like any other library

gem 'geo_ppp'

and run bundle

bundle install

now you can call it anywhere you like and it would look like this.

def index
  original_price = 79.99

  begin
    response = GeoPPPFetcher.fetch
     discounted_price = original_price * response['pppConversionFactor']
     data = { original_price: original_price, discounted_price: discounted_price }
     render json: { success: true, data: data }
  rescue StandardError => e
    render json: { success: false, error: e.message }, status: :unprocessable_entity
  end
end

That pretty much it for now. If you like this project or find it useful don't forget to give a star on github.

Monkey patching on Ruby

Waruna — Fri, 04 Oct 2024 18:33:15 +0000

Paperclip used to be a popular accessible file attachment library for ActiveRecord. However, with the introduction of ActiveStorage, its use case was replaced. It is now deprecated and does not support Ruby 3.0.

Recently, I had to work on an old Ruby on Rails app, migrating it from Ruby 2.7 to Ruby 3.0. However, moving all the paperclip logic to ActiveStorage was impossible, given the time and budget constraints.

But I was getting the following error:

undefined method escape' for URI:Module

module Paperclip
class UrlGenerator
  def escape_url(url)
    else
      URI.escape(url).gsub(escape_regex){|m| "%#{m.ord.to_s(16).upcase}" }
     end
   end
  end
end

After researching, I found out this error happens because URI.escape was deprecated in Ruby 2.7 and removed in Ruby 3.0. This is where monkey patching comes in.
In Ruby, a Monkey Patch is a dynamic modification to a class, which means adding new or overwriting existing methods at runtime. Ruby provides this ability to give coders more flexibility.

To fix this, we can rewrite the escape_url method to use an alternative way to escape URLs, such as URI::DEFAULT_PARSER.escape or CGI.escape.

So, how would you do this? First, create a monkey patch file in the config/initializers directory. So it will be loaded when the project runs.

# config/initializers/paperclip_monkeypatch.rb

module Paperclip
  class UrlGenerator
    # Monkey patch to replace the deprecated URI.escape with URI::DEFAULT_PARSER.escape
    def escape_url(url)
      if url.respond_to?(:escape)
        url.escape
      else
        # Use URI::DEFAULT_PARSER.escape to handle the escaping
        URI::DEFAULT_PARSER.escape(url).gsub(escape_regex) { |m| "%#{m.ord.to_s(16).upcase}" }
      end
    end
  end
end

URI::DEFAULT_PARSER.escape: This is the recommended alternative to URI.escape, which provides similar functionality for escaping URLs.

Restart Rails server to apply the change.

This should resolve the undefined method 'escape' error in Paperclip. I want to highlight that this is not a recommended method. It is only a quick solution, a bandage, so to speak. I'm planning to move this project to active storage as soon as possible, but this might come in handy for your hobby project or as a quick fix.

Generating dynamic layouts in Vue using recursive components

Waruna — Fri, 04 Oct 2024 17:58:33 +0000

Inspiration for this article comes from a recent implementation I did to build dynamic layouts on Vue based front end.

Let's assume your API endpoint returns a YAML layout like below.

---
row:
  - col: 12
    row:
      - col: 12
        component_id: 1
  - col: 12
    row:
      - col: 6
        component_id: 2
      - col: 6
        row:
          - col: 12
            component_id: 3
          - col: 12
            component_id: 4

We would expect a layout like the below from this YAML expression.

So, it make this easy to work with we will parse this YAML structure and generate JSON object. I used yaml package.

npm install yaml

Then, we could import it and run the parser.

import YAML from 'yaml'
const jsonObject = YAML.parse(yaml_struct)

To make this work, we need to create a recursive Vue template and a component that can call itself recursively when encountering nested rows. This way, the structure will dynamically handle deeply nested layouts like the one I provided.

<template>
    <v-row>
        <template v-for="col in row">
            <v-col :cols="col.col">
                <template v-if="col.component_id">
                    <ComponentWantToRender :col="col"></ComponentWantToRender>
                </template>

                <template v-if="col.row">
                    <RecursiveRow :row="col.row"></RecursiveRow>
                </template>
            </v-col>
        </template>
    </v-row>
</template>

<script setup>
import { defineProps } from 'vue';
import RecursiveRow from './RecursiveRow.vue';
defineProps({
    row: Array,
});
</script>

Now, we can use this RecursiveRow component inside your parent component to handle the top-level layout.

<template>
  <RecursiveRow :row="jsonObject"></RecursiveRow>
</template>

<script setup>
import RecursiveRow from './RecursiveRow.vue';

defineProps({
  jsonObject: Array,
});
</script>

You can find full working version of this here: Github Link

That's it. If you have any questions, please leave a comment below.