Skip to content

CLAUDE.md

Latest commit

 

History

History
80 lines (61 loc) · 3.34 KB

CLAUDE.md

File metadata and controls

80 lines (61 loc) · 3.34 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Intent

api2cli is a Rust binary that exposes a generic REST endpoint and proxies incoming HTTP requests to CLI apps or downstream API apps. It translates HTTP request parameters/body into CLI arguments or forwarded API calls, and streams the response back to the caller.

It is currently at the initial scaffold stage.

Commands

cargo build          # compile
cargo run            # build and run
cargo test           # run all tests
cargo test <name>    # run a single test by name
cargo clippy         # lint
cargo fmt            # format

Architecture

  • Binary crate: entry point at src/main.rs
  • Rust edition 2024
  • No dependencies added yet; expected additions: clap (CLI parsing), axum or actix-web (HTTP server), reqwest or hyper (HTTP client/proxy), serde/serde_json (serialization), tokio (async runtime)

Workflow Orchestration

Plan Mode Default

  • Enter plan mode for ANY non-trivial task (3+ steps or architectural decisions)
  • If something goes sideways, STOP and re-plan immediately - don't keep pushing
  • Use plan mode for verification steps, not just building
  • Write detailed specs upfront to reduce ambiguity

Subagent Strategy

  • Use subagents liberally to keep the main context window clean
  • Offload research, exploration, and parallel analysis to subagents
  • For complex problems, throw more compute at it via subagents
  • One tack per subagent for focused execution

Self-Improvement Loop

  • After ANY correction from the user: update tasks/lessons.md with the pattern
  • Write rules for yourself that prevent the same mistake
  • Ruthlessly iterate on these lessons until mistake rate drops
  • Review lessons at session start for relevant project

Verification Before Done

  • Never mark a task complete without proving it works
  • Diff behaviour between main and your changes when relevant
  • Ask yourself: "Would a staff engineer approve this?"
  • Write tests that provide real demonstration of working code, no mock tests, no always true tests
  • Run tests, check logs, demonstrate correctness

Demand Elegance (Balanced)

  • For non-trivial changes: pause and ask "Is there a more elegant way?"
  • If a fix feels hacky: "Knowing everything I know now, implement the elegant solution"
  • Skip this for simple, obvious fixes - don't over engineer
  • Challenge your work before presenting it

Autonomous Bug Fixing

  • When given a bug report: just fix it. Don't ask for hand holding
  • Point at logs, errors, failing tests - then resolve them
  • Zero context switching required from the user
  • Go fix failing CI tests without being told how

Task Management

  1. Plan First: Write plan to tasks/todo.md with checkable items
  2. Verify Plan: Check in before starting implementation
  3. Track Progress: Mark items complete as you go
  4. Explain Changes: High-level summary at each step
  5. Document Results: Add review section to tasks/todo.md
  6. Capture Lessons: Update tasks/lessons.md after corrections

Core Principles

  • Simplicity First: Make every change as simple as possible. Impact minimal code.
  • No laziness: Find root causes. No temporary fixes. Senior developer standards.
  • Minimal Impact: Changes should only touch what's necessary. Avoid introducing bugs.