Jan Novak
13a562e966
Makefile: add hx-* targets (deps, run, lint, fmt, test, test-integration, check, clean) that delegate into hxprobe/ via uv; fold hx-test and hx-check into the umbrella test/check/clean targets; add HX_DIR variable and a note that hxprobe is intentionally standalone (no cross-imports from python/). CLAUDE.md: add "Implementation Summaries" convention — after each feature, save a summary under docs/summaries/ with the same timestamp+slug naming as plans. Add note about copying plan-mode scratch files into docs/plans/ before starting implementation. .gitignore: add *.egg-info/, .pytest_cache/, .ruff_cache/ for the hxprobe uv+ruff+pytest toolchain. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2.3 KiB
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
If a plan is drafted via plan-mode tooling that restricts writes to a separate
scratch file, copy the approved plan verbatim into docs/plans/ as the first
implementation step, before making any code changes. The scratch file existing
elsewhere does not satisfy this convention.
Implementation Summaries
After finishing the implementation of a feature, save a summary under
docs/summaries/ with a filename that starts with the current timestamp in
yyyy-mm-dd-hh-mm format followed by a short kebab-case description (same
convention as plans). The summary covers what was actually built (as opposed
to the plan, which covers what was intended): files added/changed, key design
decisions, any deviations from the plan, notable findings made along the way,
and how it was verified.
Example: docs/summaries/2026-07-02-00-29-py-hxprobe-httpx.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
- Go implementation — developed first, incrementally, with user sign-off between steps.
- 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 |