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>
59 lines
2.3 KiB
Markdown
59 lines
2.3 KiB
Markdown
# 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
|
|
|
|
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 |
|