habedi-work/nix-playgraound
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update the AGENTS.md and make it more robust to change

Browse Source
This commit is contained in:
Hassan Abedi 2026-04-23 13:43:01 +02:00
parent 52aea18780
commit 524ef75505
1 changed files with 16 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
AGENTS.md
View File

@ -42,18 +42,23 @@ Quick examples:
## Repository Layout ## Repository Layout
- `01-devshell/`, `02-*/`, `NN-<topic>/`: self-contained numbered examples. Each directory is a flake root. - `NN-<topic>/`: self-contained numbered examples. Each matching top-level directory is a flake root.
- `notes/`: prose companions numbered to match reading order. - `notes/NNN-*.md`: prose companions numbered to match reading order.
- `001-glossary.md`: vocabulary reference. - Lower note numbers cover shared foundations such as the glossary, the Nix language, and flakes.
- `002-nix-primer.md`: the Nix language and store model. - Later note numbers may cover specific example tracks or cross-example guides.
- `003-flakes.md`: flake anatomy, schema, and common patterns.
- `Makefile`: discovery-based helpers that run formatting, linting, and `nix flake check` across all examples. - `Makefile`: discovery-based helpers that run formatting, linting, and `nix flake check` across all examples.
- `AGENTS.md`: this file. - `AGENTS.md`: this file.
- `.pre-commit-config.yaml`, `.editorconfig`, `.gitattributes`, `.gitignore`: repository hygiene. - `.pre-commit-config.yaml`, `.editorconfig`, `.gitattributes`, `.gitignore`: repository hygiene.
- `pyproject.toml`: Python environment metadata used only to install `pre-commit`. - `pyproject.toml`: Python environment metadata used only to install `pre-commit`.
New examples follow `NN-<short-topic>/` where `NN` is a two-digit ordinal. Topics grow roughly from simpler to more involved: dev shell, package, New examples follow `NN-<short-topic>/` where `NN` is a two-digit ordinal.
multi-system, NixOS module, home-manager, overlay.
Do not assume the directory list or note list in this file is exhaustive. The repository is expected to grow over time, and agents should discover the
current layout from the filesystem when needed.
Example ordering should still feel like a readable path from simpler to more involved, but the repository may branch into themed subtracks, for example
Nix and flake outputs, Haskell with Nix, or future ecosystem-specific tracks. Keep each example focused on one concept even when the broader sequence
branches.
## Example Layout Constraints ## Example Layout Constraints
@ -104,6 +109,9 @@ Example scopes that are good first tasks:
- Add a short section to `notes/003-flakes.md` referencing a newly added example. - Add a short section to `notes/003-flakes.md` referencing a newly added example.
- Convert an existing example from a hand-rolled `forAllSystems` to `flake-utils`, or vice versa, with a comment explaining the tradeoff. - Convert an existing example from a hand-rolled `forAllSystems` to `flake-utils`, or vice versa, with a comment explaining the tradeoff.
When the repository contains multiple themed tracks, "the nearest existing example" means the nearest example in the relevant track, not necessarily the
numerically closest directory overall.
## Testing Expectations ## Testing Expectations
- This repository has no runtime test suite; "tests" are `nix flake check` outcomes and successful builds of each example's default output. - This repository has no runtime test suite; "tests" are `nix flake check` outcomes and successful builds of each example's default output.
@ -152,6 +160,7 @@ Use this review format:
- If two examples disagree on a convention, prefer the newer one and update the older example in a dedicated commit. - If two examples disagree on a convention, prefer the newer one and update the older example in a dedicated commit.
- When uncertain whether a concept deserves its own example, start by expanding the notes; promote to an example once the idea stabilizes. - When uncertain whether a concept deserves its own example, start by expanding the notes; promote to an example once the idea stabilizes.
- Keep presentational prose in `notes/`. Keep runnable material in numbered directories. Do not cross the streams. - Keep presentational prose in `notes/`. Keep runnable material in numbered directories. Do not cross the streams.
- Prefer layout guidance based on naming patterns and discovery, not hard-coded counts of examples or notes. If you need the current tree, inspect it.
- Keep user-facing naming consistent with the repository name: `nix-playground`. The directory spelling `nix-playgraound` is intentional and should - Keep user-facing naming consistent with the repository name: `nix-playground`. The directory spelling `nix-playgraound` is intentional and should
not be "fixed". not be "fixed".