docs: add AGENTS.md and model-selection guidance#94
Open
felipebalbi wants to merge 2 commits into
Open
Conversation
Document the per-segment working-directory rules, the exact CI commands run by check.yml / uefi-check.yml / cargo-vet.yml, and the Rust workspace conventions (rustfmt, lints, MSRV, resolver, vendored dependency pins) that aren't obvious from a casual read of the tree. Also surface the drop-safety and panic-safety review hints from copilot-instructions.md so any agent reading AGENTS.md alone still gets the warnings. Assisted-by: GitHub Copilot:claude-opus-4.7
Adds guidance on choosing between premium and cheap models for code-assistant work, including escalation/de-escalation triggers, sub-agent routing defaults, /fleet rules, and session-hygiene tips. Keeps premium reasoning for genuinely hard problems and routes mechanical work to cheaper models. Assisted-by: GitHub Copilot:claude-opus-4.7
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a repository-specific AGENTS.md intended to give AI coding agents a single place to learn the repo’s segment layout (ec/ vs uefi/), the CI-aligned command set, and key conventions/pitfalls, plus a section on model selection and cost discipline.
Changes:
- Introduces
AGENTS.mddescribing repo structure, working-directory rules, and CI-equivalent commands forec/anduefi/crates/patina_tianocore/. - Documents Rust/workspace conventions (MSRV, clippy policy, workspace dependencies, cargo-vet store, Windows cross-compile alias, SPDX guidance).
- Adds “Model selection & cost discipline” guidance for agent workflows.
| @@ -0,0 +1,198 @@ | |||
| # AGENTS.md | |||
|
|
|||
| Guidance for AI coding agents working in `openDevicePartnership/odp-platform-common`. | |||
| -Dwarnings -D clippy::suspicious -D clippy::correctness -D clippy::perf -D clippy::style | ||
| cargo hack --feature-powerset clippy --locked -p ec-test-tui -- \ | ||
| -Dwarnings -D clippy::suspicious -D clippy::correctness -D clippy::perf -D clippy::style | ||
| cargo deny check --manifest-path Cargo.toml # or: from repo root, --manifest-path ec/Cargo.toml |
Comment on lines
+53
to
+55
| Required tools: `cargo-hack`, `cargo-deny`, `cargo-machete`, plus a nightly toolchain for `doc`. Install with `cargo install cargo-hack cargo-deny cargo-machete` and `rustup toolchain install nightly`. | ||
|
|
||
| The CI `clippy` matrix is `{stable, beta} × {ubuntu, windows} × {ec-test-cli, ec-test-lib, ec-test-tui}`. Locally, stable on your host OS is usually enough; rely on CI for the rest. |
| - **Lints**: The `ec/` workspace denies `clippy::{suspicious, correctness, perf, style}` at the workspace level. New code must not introduce warnings under these groups. | ||
| - **Edition / MSRV**: `ec/` uses edition `2024`, MSRV `1.88`. `uefi/crates/patina_tianocore` uses edition `2024`, MSRV `1.89` and requires the pinned nightly for unstable features. | ||
| - **Resolver**: `ec/` uses `resolver = "3"`. Do not downgrade. | ||
| - **Dependencies**: Add workspace-shared crates to `[workspace.dependencies]` in `ec/Cargo.toml` and reference them from members with `dep = { workspace = true }`. Service-message crates come from `OpenDevicePartnership/embedded-services` on branch `v0.2.0` — keep that pin consistent. |
|
|
||
| - **Async drop safety**: code using `select`, `selectN`, `select_array`, `select_slice` (or carrying a drop-safety comment) drops the un-selected futures. When editing such code, verify no message/value is lost on the dropped branch. | ||
| - **Panic-prone code**: any function marked with a panic-safety comment is intentionally narrow about its invariants. Preserve those invariants when refactoring. | ||
| - **Submodules**: the repo has submodules (`.gitmodules`). Use `git checkout --recurse-submodules` and clone with `--recursive`; CI always passes `submodules: true` to `actions/checkout`. |
Comment on lines
+95
to
+101
| These come from `.github/copilot-instructions.md` and `CONTRIBUTING.md`. Highlights an agent must follow: | ||
|
|
||
| - **Subject**: ≤ 50 chars, capitalized, imperative ("Fix bug", not "Fixed bug"). Blank line, then body wrapped at 72 chars explaining *what* and *why*. | ||
| - **AI attribution**: every AI-assisted commit **must** carry an `Assisted-by:` trailer, e.g. `Assisted-by: GitHub Copilot:claude-opus-4.7`. Verify the actual agent name and model version at commit time — do not copy from a previous session. | ||
| - **No `Signed-off-by`**: agents must not add DCO sign-offs; only humans can certify the DCO. | ||
| - **PR flow**: open a **draft** PR first and wait for `check`, `uefi-check`, and `cargo-vet` workflows to pass before requesting review. | ||
| - **Authorship**: set commit author per invocation with `git -c user.name=... -c user.email=...`; do not change global git config. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR adds an
AGENTS.mdfile (see agents.md) tailored to this repository, distilled from the project's CI workflows, configuration, source layout, and conventions. The goal is to give any AI coding agent (Copilot, Claude, Cursor, etc.) enough repo-specific context to be immediately productive without re-deriving conventions from scratch.Commit 1 —
docs: add AGENTS.md ...AGENTS.mdwith project overview, build/test/lint/fmt commands, code layout, contribution patterns, and any quirks observed (e.g.,defmtfeature constraints, nightly-onlyrustfmt.tomloptions, workspace layout)..github/copilot-instructions.mdupdated to point atAGENTS.mdas the authoritative source, so Copilot-specific configuration does not drift out of sync with the broader agent guidance. Where nocopilot-instructions.mdexisted, a minimal pointer file was added.Commit 2 —
docs(AGENTS.md): add model selection & cost discipline section/fleetrules, and session-hygiene tips. The aim is to keep premium reasoning for genuinely hard work and route mechanical edits to cheaper models, reducing wasted spend without sacrificing quality.No source code, dependencies, or CI behavior is changed by this PR — it is documentation only.
Marked as draft for review; happy to iterate on tone, scope, or any repo-specific detail that should be tightened up.
Assisted by GitHub Copilot (Claude Opus 4.7).