# AGENTS.md
Context for any AI coding agent working in this repo (Claude Code, OpenCode, Cursor,
Codex, Aider, Zed, …). Keep this file short and authoritative — anything that grows
beyond a quick reference belongs in a dedicated doc and should be linked from here.
## Project
`tiny-tracing` is a lightweight, builder-style Rust logging library that wraps
[`tracing`](https://crates.io/crates/tracing) and
[`tracing-subscriber`](https://crates.io/crates/tracing-subscriber). It provides a
fluent API to configure and initialise the global tracing subscriber with text or
JSON output, optional `EnvFilter` support, and safe initialisation (no panics on
double-init).
Source layout:
- `src/lib.rs` — crate root, re-exports `tracing` macros (`info!`, `warn!`, …) and
`config::Logger`.
- `src/config.rs` — `Logger` builder: level, format, env filter, file/target flags,
and `init()` that calls `try_init()` under the hood.
- `src/errors.rs` — `LoggerError` enum (`InvalidLevel`, `InvalidFormat`, `TryInitError`)
derived with `thiserror::Error`.
- `src/time.rs` — `LocalTimer`, a `FormatTime` impl that uses `chrono::Local`.
- `tests/logger.rs` — integration tests for builder config and `init()` behaviour.
## Setup & common commands
Rust toolchain is pinned via `rust-toolchain.toml` (currently 1.96.1).
```bash
cargo test # unit + integration + doc-tests
cargo fmt --all -- --check # check formatting
cargo clippy --all-targets --all-features -- -D warnings
cargo publish --dry-run # verify crate packages correctly
```
Run a single integration test: `cargo test --test logger <test_name>`.
## Conventions
- **Commits**: Conventional Commits, enforced by [cocogitto](https://docs.cocogitto.io/).
Use `cog commit <type> "<msg>" [scope]` rather than `git commit -m`. Common types:
`feat`, `fix`, `chore`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`.
- **No `unsafe`** anywhere in the crate. Dependencies may use unsafe; that is acceptable.
- **Pre-commit hook** (`pre-commit.sh`) runs `pre-commit run -a`, `cargo nextest run`,
`cargo fmt`, and `cargo check`. If a hook fails, fix the underlying issue and create
a NEW commit — do not bypass with `--no-verify`.
- **Documentation hygiene**: every code change must be accompanied by a sweep of the
doc surface. Before declaring a task done or shipping a release, review `README.md`,
`AGENTS.md`, and the relevant `.claude/skills/**/SKILL.md`, and update whatever has
drifted. Update docs in the same commit as the code when feasible, or as an immediate
follow-up. `CHANGELOG.md` is regenerated by `cog changelog` and must not be edited
by hand.
- **Codebase-memory index hygiene**: whenever code or another important part of the
repo changes (source under `src/`, `tests/`, `Cargo.toml` deps, `cog.toml`,
`.github/workflows/`, `AGENTS.md`, or `deny.toml`), re-index the project into
`codebase-memory` so future graph/trace queries stay accurate. Do this as a
persistent habit — do not wait to be asked.
- **Imports**: `std` first, then external crates, then `crate::`. `rustfmt` handles
the ordering via edition 2024 defaults.
## Releases
The full release workflow is documented in the [release skill](.claude/skills/release/SKILL.md).
In short, new versions are cut with cocogitto:
```bash
cog bump --auto # auto-detects semver from commits since last tag
cog bump --version X.Y.Z # explicit version
```
`cog.toml`'s `pre_bump_hooks` update `Cargo.toml` (via `cargo set-version`), refresh
`Cargo.lock`, and regenerate `CHANGELOG.md`. The `Cargo.toml` version and the latest
git tag MUST stay in sync — verify before and after.
Required local tools: `cog` (cocogitto 7+) and `cargo-set-version` (from `cargo-edit`).
After `cog bump`, push the tag manually:
```bash
git push origin main
git push origin X.Y.Z
```
Pushing a `*.*.*` tag triggers the `publish-crate` CI job which runs
`cargo publish --locked` to crates.io.
## CI
`.github/workflows/test.yml` runs on PRs, pushes matching the path filter, and tag
pushes. Jobs: `security` (cargo-audit + cargo-deny), `linting` (fmt + clippy),
`test` (x86_64 + aarch64 matrix), `publish-crate` on tag. The `security` job also
runs weekly on a cron (`0 7 * * 1`) to surface new advisories.
`cargo-deny` policy lives in `deny.toml` — keep advisories at `version = 2` and only
permissive licenses allowed. The project itself is MIT-licensed.
## Things to avoid
- Do not skip pre-commit hooks (`--no-verify`).
- Do not bump the version manually in `Cargo.toml` — use `cog bump`.
- Do not edit `CHANGELOG.md` by hand — it is regenerated by `cog changelog`.
- Do not commit credentials or secrets of any kind.
- Do not commit scratch, review, or analysis files (e.g. `review.md`, `notes.md`,
`plan.md`) that you produce as intermediate artifacts while working on a task.
Keep them out of the repo. Before committing, `git status` the tree and drop
anything that is not part of the actual change.
- Do not add `unsafe` code — keep the crate safe-Rust only.