# CLAUDE.md — Working Conventions

This file records the conventions Claude must follow throughout this project.

## Plans

Every implementation plan is saved under `docs/plans/` with a filename that
starts with the **current timestamp in `yyyy-mm-dd-hh-mm` format** followed by
a short kebab-case description.

Example: `docs/plans/2026-07-01-00-08-go-latency-tool.md`

## Changelog

Every completed feature is appended to `CHANGELOG.md` at the project root with
a **timestamp** and a one-line description of what was added or changed.

## User Documentation

Every shipped feature must have a corresponding documentation file under
`docs/usage/`. Each file must include:
- What the feature does
- All relevant flags / arguments
- At least one concrete command-line example with expected output

## Implementation Order

1. Go implementation — developed first, incrementally, with user sign-off
   between steps.
2. Python port — begins only after the user approves the Go implementation.
   Its plan is drafted separately at that time.

## Steps (Go)

| Step | Description |
|------|-------------|
| 0    | Scaffold — directory structure, `go.mod`, minimal `main.go` that prints usage |
| 1    | Simple total latency — single URL, print wall-clock time of the full request |
| 2    | Per-phase breakdown — DNS, TCP connect, TLS, TTFB, transfer, total via `net/http/httptrace` |
| 3    | Multiple URLs + sampling — `--count`/`-n` flag, min/avg/max per phase |
| 4    | JSON output — `--json` flag; text stays default |