Skip to content

AGENTS.md

Latest commit

 

History

History
95 lines (71 loc) · 7.77 KB

AGENTS.md

File metadata and controls

95 lines (71 loc) · 7.77 KB
Raw

Agent Guide

AGENTS.md is the writable source of truth for agent-facing instructions in this repository.

Start Here

  • Prefer Serena symbolic retrieval for Go source structure before broad source-file reads.
  • For repo edits, read current files first and keep changes surgical. Do not revert unrelated user changes.
  • This repo has no top-level go.mod; run Go commands from the individual module directory unless using an explicit loop.
  • CI runs only on the GitHub mirror through .github/workflows/; Gitea is the primary source remote and must not contain .gitea/workflows/ CI definitions.

Project Map

This is a collection of five standalone Go CLI tools plus one shared module. Each tool has its own module and builds independently.

Area Purpose Read first
api-stress-test/ HTTP load/stress tester with strict pacing, graceful drain, streaming response validation, and schema-v2 reports. api-stress-test/cmd/root.go, api-stress-test/cmd/lifecycle.go, then docs/agent/api-stress-test.md
check-folder-size/ Directory size analyzer with terminal and JSON output. check-folder-size/cmd/root.go, check-folder-size/internal/scanner/
find-content/ Deterministic bounded text search with hidden/special-file policies and directory listing. find-content/cmd/root.go, find-content/internal/searcher/
find-everything/ Bounded concurrent file finder with partial reports, TTY-safe output, and atomic large-result saves. find-everything/cmd/root.go, find-everything/internal/finder/finder.go
replace-text/ Streaming find/replace CLI with backups, dry-run, size limits, metadata preservation, and atomic writes. replace-text/cmd/root.go, replace-text/internal/replacer/
common-module/ Shared utilities used by check-folder-size. common-module/utils/

For detailed package routing, read docs/agent/project-map.md.

Common Workflows

  • Build one tool locally without installing:
cd <tool-dir> && go build -o <tool-name> .
  • Test one module:
cd <tool-dir> && go test ./...
  • Run the focused api-stress-test benchmark:
cd api-stress-test && go test ./... -run '^$' -bench 'Benchmark(CollectorRecord|ResponseBodyStreaming|SchedulerIntegration)$' -benchmem
  • Repeat the concurrency-sensitive find-everything finder tests:
cd find-everything && go test ./internal/finder -run 'Test.*(Limit|Queue|Cancel|Partial)' -count=20
  • Build or install through Makefile only when that is intended. make targets move binaries outside the repo: macOS to $(HOME)/dev-kit/tool, Linux to /usr/local/bin, Windows/MSYS to D:/dev-kit/tool.
  • Clean build artifacts with make clean. Unix binaries produced inside tool directories are not ignored by .gitignore.

For all-module loops, Makefile caveats, tidy, vet, and release notes, read docs/agent/workflows.md.

Task Routing

  • Changing CLI flags, command validation, streams, or exit behavior: read the tool's cmd/root.go, its command tests, and docs/agent/cli-conventions.md.
  • Changing terminal output or JSON output: read the relevant internal/ui/ package or single-file CLI output functions first.
  • Changing api-stress-test HTTP bodies, timing, expectations, or rate pacing: read api-stress-test/internal/request/client.go, matcher.go, and ratelimiter.go.
  • Changing api-stress-test scheduling, warmup, shutdown, signals, exit codes, TTY behavior, or report files: read api-stress-test/cmd/lifecycle.go, its tests, and docs/agent/api-stress-test.md.
  • Changing api-stress-test metrics, schema, percentiles, histograms, or throughput: read api-stress-test/internal/stats/collector.go, api-stress-test/internal/ui/output.go, and docs/agent/api-stress-test.md.
  • Changing filesystem traversal/search: read check-folder-size/internal/scanner/scanner.go, find-content/internal/searcher/, or find-everything/internal/finder/ as appropriate.
  • Changing check-folder-size accounting or platform metadata: read check-folder-size/internal/scanner/types.go, scanner.go, metadata.go, the target metadata_<os>.go, and matching scanner tests; use check-folder-size/go.mod as the toolchain/dependency source of truth.
  • Changing replace-text flags, validation, output, or exit behavior: read replace-text/cmd/root.go and replace-text/cmd/root_test.go.
  • Changing replace-text traversal, streaming, size limits, backup/atomic-write behavior, or metadata preservation: read replace-text/internal/replacer/processor.go, replace-text/internal/replacer/stream.go, replace-text/internal/replacer/metadata.go, and their matching tests first.
  • Changing shared utilities: read common-module/utils/, then build/test every consumer that imports common-module/utils.
  • Changing tests or verification strategy: read docs/agent/testing.md.
  • Changing CI or mirror behavior: read the affected .github/workflows/*-ci.yml file and docs/agent/workflows.md; do not add Gitea Actions workflows.
  • Changing build/install behavior: read Makefile and docs/agent/workflows.md.

Conventions And Guardrails

  • After every code change, update agent docs when the change affects knowledge future sessions need. Keep AGENTS.md token-efficient; put details in the relevant docs/agent/ file and add read-on-demand routing.
  • Always communicate with users in the language they use. Do not reply in English unless the user's prompt is in English.
  • Golden rule: no workaround.
  • Treat any user request assessed as a breaking or large change as plan-first work: switch to Plan mode before implementation. If Plan mode is unavailable at runtime, stop immediately and ask the user whether to switch to Plan mode.
  • Code comments must be brief and concise; avoid long explanations.
  • Use each module's go.mod and affected CI workflow as the Go toolchain/dependency source of truth. Keep dependencies minimal; Cobra is the CLI framework used across tools.
  • Use standard Go formatting. Run gofmt or gofmt -w only on files you intentionally changed.
  • Error handling should use contextual fmt.Errorf("...: %w", err) where wrapping helps callers.
  • Preserve CLI flag names and existing public behavior unless the user explicitly asks for a breaking change.
  • File safety matters: keep binary detection, UTF-8 validation, backup restore paths, and temp-file rename behavior intact.
  • Concurrency patterns use goroutines, sync.WaitGroup, channels, mutexes, and atomics. For high-concurrency api-stress-test changes, verify the tool does not bottleneck on its own collectors, progress UI, or request setup.
  • Output uses direct ANSI escape codes and standard fmt output; there is no structured logging library.

Read On Demand

  • docs/agent/project-map.md - detailed module/package map and first-read files.
  • docs/agent/workflows.md - build, test, tidy, vet, Makefile, install, and cleanup workflows.
  • docs/agent/testing.md - current test coverage, gaps, and focused verification commands.
  • docs/agent/cli-conventions.md - shared Cobra lifecycle, stream, error, compatibility, and command-test contract.
  • docs/agent/api-stress-test.md - high-concurrency stress-test architecture, data flow, performance risks, and verification.