From b1fa41d87db02f1d55465b69212444d0f087c384 Mon Sep 17 00:00:00 2001 From: Aaron Gonzales Date: Fri, 16 Oct 2026 21:00:12 +0000 Subject: [PATCH] docs: add shared coding-agent guidance Signed-off-by: Aaron Gonzales --- .agents/README.md | 10 ++++++++ .gitignore | 17 ++++++++++++++ AGENTS.md | 59 +++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + CONTRIBUTING.md | 5 ++++ 5 files changed, 92 insertions(+) create mode 100644 .agents/README.md create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.agents/README.md b/.agents/README.md new file mode 100644 index 0000000..511c2a5 --- /dev/null +++ b/.agents/README.md @@ -0,0 +1,10 @@ +# Coding-agent guidance + +[AGENTS.md](../AGENTS.md) is the shared instruction source for developing +UserSim. [CLAUDE.md](../CLAUDE.md) points to it for Claude Code. + +Keep shared guidance here and development commands in Make. Keep personal +instructions in ignored `AGENTS.local.md`, `CLAUDE.local.md`, or `.agents/local/`; +keep private logs and session artifacts in `.agents/logs/`, `.agents/sessions/`, +or `.agent-work/`. Keep credentials and client settings out of shared files. +Local instructions may need explicit loading by the client. diff --git a/.gitignore b/.gitignore index 5942f4e..6ec015e 100644 --- a/.gitignore +++ b/.gitignore @@ -63,3 +63,20 @@ Thumbs.db # Cursor .cursor/ + +# Private agent overrides and session artifacts; shared guidance stays trackable. +AGENTS.local.md +CLAUDE.local.md +.agents/local/ +.agents/logs/ +.agents/sessions/ +.claude/settings.json +.claude/settings.local.json +.claude/logs/ +.claude/hooks/ +.codex/config.toml +.codex/config.local.toml +.codex/hooks.json +.codex/sessions/ +.worktrees/ +/.agent-work/ diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..6e88940 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,59 @@ +# Developing UserSim + +This file is for coding agents developing UserSim. To use UserSim, start with +[README.md](README.md). For contribution policy and setup, read +[CONTRIBUTING.md](CONTRIBUTING.md); for the system map, read +[architecture/overview.md](architecture/overview.md). + +UserSim generates persona-grounded conversations, evaluates trajectories, and +produces reports and selected datasets. Its simulator and evaluator are Data +Designer column generators; reuse Data Designer's orchestration, parallelism, +and provider handling rather than implementing a second execution framework. + +## Module map + +| Path under `src/usersim/` | Owns | +| --- | --- | +| `cli/` | Command arguments, configuration loading, and pipeline orchestration. | +| `engine/config.py`, `engine/core/` | Simulation configuration, conversation runtime, model calls, and storage. | +| `engine/probes/`, `engine/assets/` | Probe behavior, prompts, and shipped asset banks. | +| `engine/evaluator/` | Evaluation configuration, rubric axes, and scorers. | +| `reporting/`, `selection/` | Reports, selection profiles, quality gates, and exports. | +| `taxonomy/` | Shared capability vocabulary and evaluation-cell decoding. | +| `asset_gen/`, `testing/` | Asset generation and conformance checks for extension authors. | + +## Preserve the contracts + +- Keep behavior with its owning module and follow neighboring code. Search for + existing helpers before adding configuration, credential, or registry logic. +- Preserve the dependency boundaries in the architecture guide. Shared + capability definitions belong in `taxonomy/`, where configuration and reporting + can both use them without reversing their dependency direction. +- Changes to prompts, probes, assets, or scorers can change experimental results + even when tests pass. Explain that impact in the PR and update relevant docs. +- UserSim's extension entry points are separate from its two Data Designer + plugins. For extension work, read [architecture/plugins.md](architecture/plugins.md); + for probes, read [the authoring guide](docs/engine/AUTHORING_A_PROBE.md). + +## Develop and validate + +Use Make and uv; `make help` lists the available targets. Reuse an existing +suitable environment for investigation; sync when setup or dependencies require it. + +```bash +make install-dev # sync dependencies and install hooks +make check-all # read-only lint and format checks +make test PYTEST_ARGS='tests/test_cli.py -q' PYTEST_WORKERS=2 +make check-doc-links # check repository documentation links +``` + +Test changed behavior and integration boundaries, using focused tests first. +Run packaging checks when installed-package behavior changes; see CONTRIBUTING +for the existing targets. Keep ordinary tests free of live provider calls. +`make health-check` is a separate credentialed operation; report whether it ran. + +Follow the PR template and use `git commit --signoff` for DCO compliance. +Report exact checks and outcomes, including checks not run; do not claim human +review or live-provider acceptance without evidence. Keep durable contracts in +source docstrings and relevant docs. See [.agents/README.md](.agents/README.md) +for shared guidance and private local files. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b70a817..a7aa99e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -88,6 +88,11 @@ passes the check automatically. this project or the open source license(s) involved. ``` +## Coding-agent guidance + +Coding agents developing UserSim should start with [AGENTS.md](AGENTS.md). +See [.agents/README.md](.agents/README.md) for shared guidance and private local files. + ## Getting set up Requires Python 3.10 to 3.14 and [uv](https://docs.astral.sh/uv/).