personal-finance
AGENTS.md1 starsChanged todayMITView on GitHub
Instructions for AI coding agents (Claude Code, Codex, Cursor) working in this repository. Humans: see CONTRIBUTING.md. The binding rules are in .specify/memory/constitution.md. The short version: Project rules that add to or override the generic stack rules below live in .claude/rules/project/ (Cursor: .cursor/rules/project-*.mdc): backend.md, web.md, testing.md, security.md. Where they differ from a pack rule, the project rule wins. Features live in specs/<NNN-feature>/ (spec.md, plan.md, tasks.md). Implement tasks with task-loop specs/<NNN-feature>/tasks.md: one fresh agent session per task, and a task counts as…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository84 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- .cursor/rules/angular-coding-style.mdcCursor rule
- .cursor/rules/angular-patterns.mdcCursor rule
- .cursor/rules/angular-security.mdcCursor rule
- .cursor/rules/angular-testing.mdcCursor rule
- .cursor/rules/common-code-review.mdcCursor rule
- .cursor/rules/common-coding-style.mdcCursor rule
- .cursor/rules/common-development-workflow.mdcCursor rule
- .cursor/rules/common-security.mdcCursor rule
- .cursor/rules/common-testing.mdcCursor rule
- .cursor/rules/csharp-coding-style.mdcCursor rule
- .cursor/rules/csharp-data-access.mdcCursor rule
- .cursor/rules/csharp-patterns.mdcCursor rule
- .cursor/rules/csharp-security.mdcCursor rule
- .cursor/rules/csharp-testing.mdcCursor rule
- .cursor/rules/design-design-system.mdcCursor rule
- .cursor/rules/project-backend.mdcCursor rule
- .cursor/rules/project-security.mdcCursor rule
- .cursor/rules/project-testing.mdcCursor rule
- .cursor/rules/project-web.mdcCursor rule
- .cursor/rules/typescript-coding-style.mdcCursor rule
- .cursor/rules/typescript-patterns.mdcCursor rule
- .cursor/rules/typescript-security.mdcCursor rule
- .cursor/rules/typescript-testing.mdcCursor rule
- angular-guideSkill
- break-uiSkill
- dotnet-create-command-querySkill
- dotnet-create-entitySkill
- dotnet-create-moduleSkill
- dotnet-ef-migrationSkill
- emil-design-engSkill
- frontend-designSkill
- impeccableSkill
- review-animationsSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-implementSkill
- speckit-planSkill
- speckit-specifySkill
- speckit-tasksSkill
- ui-ux-pro-maxSkill
- angular-guideSkill
- break-uiSkill
- dotnet-create-command-querySkill
- dotnet-create-entitySkill
- dotnet-create-moduleSkill
- dotnet-ef-migrationSkill
- emil-design-engSkill
- frontend-designSkill
- impeccableSkill
- review-animationsSkill
- speckit-analyzeSkill
- speckit-checklistSkill
- speckit-clarifySkill
- speckit-constitutionSkill
- speckit-convergeSkill
- speckit-implementSkill
- The first 60 shown.
The file
We split this AGENTS.md into the rules it gives an agent
10 rules. About 1 is common, 6 are distinctive, and 3 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈6
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Read-only brokers: Never write code that places orders, moves money or withdraws.
- Distinctive: line 12
Test-first: Every behaviour change starts with a failing test.
- Very specific: line 73
Follow the repo's application structure: feature slices with minimal APIs, CQRS handlers behind a mediator (<Verb><Entity>Command/Query), …
- Distinctive: line 96
Test-first by user-visible behaviour, with the repo's runner (Vitest and Testing Library by default).
- Very specific: line 98
No secrets or tokens in the browser: public env prefixes (NEXT_PUBLIC_, VITE_) are public.
- Distinctive: line 114
Check the installed Angular version first.
- Distinctive: line 118
Every UI string goes into every language file in the same change.
- Common: line 148
Never paste secrets, tokens, real user data or client data into a prompt or a finding.
- Distinctive: line 171
Review a screen: Run the app and look at it before judging it: light and dark, 375 px and 1440 px, keyboard only.
- Very specific: line 174
Keep it consistent: Use tokens, never hard-coded values.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
AGENTS.md
Instructions for AI coding agents (Claude Code, Codex, Cursor) working in this repository. Humans: see CONTRIBUTING.md.
Rules
The binding rules are in .specify/memory/constitution.md. The short version:
- Read-only brokers. Never write code that places orders, moves money or withdraws.
- Money is
decimal; the backend calculates, the UI only displays. - Test-first. Every behaviour change starts with a failing test.
- No personal data anywhere: synthetic data and the demo broker only.
- Architecture, security or data decisions get a new ADR in
docs/adr/; merged ADRs are never edited.
Project rules that add to or override the generic stack rules below live in .claude/rules/project/ (Cursor:
.cursor/rules/project-*.mdc): backend.md, web.md, testing.md, security.md. Where they differ from a pack
rule, the project rule wins.
Workflow
| Size | Process |
| Bug fix, small change | A task with acceptance criteria → test-first → pull request |
| Feature | /speckit-specify → /speckit-plan → /speckit-tasks → human review of spec and tasks → implement |
Features live in specs/<NNN-feature>/ (spec.md, plan.md, tasks.md). Implement tasks with
task-loop specs/<NNN-feature>/tasks.md: one fresh agent session per task, and a task
counts as done only when the verification gate in .agent-loop.env passes.
Commands
cd backend && dotnet build # .NET 10 (see backend/global.json)
cd backend && dotnet format --verify-no-changes --include <files> # C# format check on the files you touch
cd backend && dotnet test --project tests/Finance.Tests # one test project (Microsoft.Testing.Platform)
cd web && npm run build # Angular build and type check
cd web && npm test && npm run lint:format # Vitest + PrettierIntegration.Tests need Docker; CI runs them on every pull request.
The whole backend is not dotnet format clean yet, so check only the files you change.
Subagents (Claude Code)
One version of each generic agent, from Armature; the project context they need is in the rules above, not in copies of the agents.
- Armature
coreplugin (user level):tdd-guide(implements one task test-first),security-reviewer(report only),build-error-resolver(minimal fixes to a broken build). - Written into
.claude/agents/by the Armature packs (managed:armature sync, never edited here):csharp-reviewer,typescript-reviewer(report only),dotnet-developer,angular-developer,design-system-guard.
Never
Merge pull requests, push to main, edit merged ADRs, weaken or skip tests, or commit secrets.
<!-- armature:stack-dotnet:start -->.NET (stack-dotnet)
Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or
AGENTS.md outside the Armature sections) differ, the repo wins.
Rules: .claude/rules/csharp/ (coding style, patterns, data access, security, testing), also rendered to
.cursor/rules/csharp-*.mdc. They load for *.cs, *.csproj and appsettings*.json. The repo's .editorconfig,
architecture doc and ADRs decide style and structure; the rules describe the defaults when the repo says nothing.
- Style follows the repo's
.editorconfig(var, namespaces, braces); nullable on. Without one, Armature's template (plugins/stack-dotnet/templates/.editorconfig) is a starting point. - Expected failures as results (
Result/Error: validation, not found, conflict, forbidden) rather than exceptions, in whatever shape the repo already uses. - Follow the repo's application structure: feature slices with minimal APIs, CQRS handlers behind a mediator
(
<Verb><Entity>Command/Query), or controllers. Do not introduce a different one in a single change. - A module owns its data: no reaching into another module's
DbContext; migrations come from the EF tool.
Skills: dotnet-create-module, dotnet-create-entity, dotnet-create-command-query (for repos that use CQRS),
dotnet-ef-migration. Official .NET skills come from the dotnet/skills marketplace (enabled in
.claude/settings.json, not copied here).
Agents: [@dotnet-developer] implements one .NET task test-first; csharp-reviewer reviews C# changes (report
only). Typical gate: dotnet build, dotnet format --verify-no-changes, dotnet test (the repo's VERIFY_CMD wins).
<!-- armature:stack-dotnet:end --><!-- armature:stack-typescript:start -->TypeScript
Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or
AGENTS.md outside the Armature sections) differ, the repo wins.
Rules: .claude/rules/typescript/ (Cursor: .cursor/rules/typescript-*.mdc), applied to *.ts, *.tsx, *.js
and test files.
- Strict TypeScript: no
any, no hiding casts, no!without a guard; schemas (e.g. Zod) at every trust boundary. - One formatter and linter, run by the gate: what the repo already uses (Biome when it has none).
- Test-first by user-visible behaviour, with the repo's runner (Vitest and Testing Library by default); Playwright for critical flows.
- No secrets or tokens in the browser: public env prefixes (
NEXT_PUBLIC_,VITE_) are public.
| Agent | Use it |
typescript-reviewer | After TypeScript changes, before a pull request. Reports findings with a verdict; never edits |
<!-- armature:stack-typescript:end --><!-- armature:stack-angular:start -->Angular
Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or
AGENTS.md outside the Armature sections) differ, the repo wins.
Rules: .claude/rules/angular/ (Cursor: .cursor/rules/angular-*.mdc), plus the TypeScript rules. Skill:
angular-guide (the official angular/skills angular-developer skill, renamed so it does not clash with the agent).
- Check the installed Angular version first; follow the CLI conventions the repo already uses.
- Defaults for new code: standalone components,
OnPush,inject(), signal inputs/outputs,resource/rxResourcefor data, block control flow withtrack. - HTTP through the repo's API service and
HttpClient, so the interceptors (session expiry, timeouts, XSRF) apply. - Every UI string goes into every language file in the same change; money and dates through the shared pipes.
- The backend computes figures; the UI only displays them.
| Agent | Use it |
angular-developer | Tasks tagged [@angular-developer]: one task, test-first |
typescript-reviewer | After web changes, before a pull request. Reports only |
<!-- armature:stack-angular:end --><!-- armature:security:start -->Security review tools
Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or
AGENTS.md outside the Armature sections) differ, the repo wins.
Nothing from this pack is copied into the repo. The security plugins are installed from upstream, at user scope, on demand (when a change touches auth, input handling, secrets, dependencies or integrations), and never vendored: Trail of Bits' skills are CC-BY-SA-4.0, which must not be mixed into the repo.
claude plugin marketplace add trailofbits/skills
claude plugin install insecure-defaults@trailofbits # hard-coded credentials, fail-open defaults
claude plugin install sharp-edges@trailofbits # error-prone APIs and dangerous configuration
claude plugin install differential-review@trailofbits # security review of a diff with git history
claude plugin install supply-chain-risk-auditor@trailofbits
claude plugin install security-guidance@claude-plugins-official # warnings on risky edits- The
security-revieweragent (Armature core) stays the first pass before a pull request; the plugins above go deeper. - Static findings come from
semgrep scan --jsonin PR Validation, not from a model. - Never paste secrets, tokens, real user data or client data into a prompt or a finding.
<!-- armature:security:end --><!-- armature:design:start -->Design work
Armature defaults. Where this repo's rules (.claude/rules/project/, other rules Armature does not manage, or
AGENTS.md outside the Armature sections) differ, the repo wins.
Work like a senior product designer, not a code generator. Start from the user's task and the evidence on screen, reuse
what the app already has before adding anything, and treat every state as a deliverable: empty, loading, partial,
error, no permission and stale. The repo's own design rules (its design-system doc and DESIGN.md) outrank any skill.
Accessibility means WCAG 2.2 AA: keyboard use, visible focus, contrast, no meaning carried by colour alone, labels.
| Skill or agent | Use it to |
impeccable | Review and improve an existing screen: critique (UX, hierarchy), audit (accessibility, performance, responsive), then polish, typeset, layout, clarify or harden. The default for "make this better" |
frontend-design | Set a new screen's direction before code: purpose, tone, hierarchy. Constrained by the repo's design rules |
ui-ux-pro-max | Look up palettes, font pairings, UX guidelines and chart types: python3 .agents/skills/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain>. Do not use --persist |
emil-design-eng + review-animations | Motion and interaction feel (easing, duration, hover and press states); review every animation before shipping; respect prefers-reduced-motion |
break-ui | Stress a screen before calling it done: long text, empty and huge data, slow network, narrow widths |
design-system-guard (agent) | Check a UI diff against the design tokens and rules: no hard-coded colours or sizes, components reused |
Review a screen. Run the app and look at it before judging it: light and dark, 375 px and 1440 px, keyboard only. Fix problems by severity and show before and after screenshots. A visual change is done only when a person has seen it.
Keep it consistent. Use tokens, never hard-coded values. Impeccable owns PRODUCT.md (users, purpose, tone;
/impeccable init) and DESIGN.md (the visual system; /impeccable document, refreshed in the same PR as a visual
change). Do not create a design-system/ folder. Keep telemetry off (DO_NOT_TRACK=1).
Vendored skills are pinned in Armature's vendor.lock.json; do not edit them in the repo (armature sync reports it).
<!-- armature:design:end --><!-- armature:core:start -->Armature (core)
Armature writes defaults into this repo: the sections between armature: markers in this file, the rules in
.claude/rules/ and .cursor/rules/, skills and agents. They are defaults, not the repo's law. Where this repo's own
rules differ (.claude/rules/project/, any other rule Armature does not manage, or AGENTS.md outside the Armature
sections), the repo wins. To change an Armature section here, use .armature/overrides.json, not an edit between
the markers (armature sync reports edits there as conflicts).
Task Loop. Implement a feature's tasks.md one task per fresh agent session, test-first; a task is done only when
the gate (VERIFY_CMD in .agent-loop.env) passes:
task-loop specs/<NNN-feature>/tasks.md # on PATH while the core plugin is enabled
"$ARMATURE_HOME/plugins/core/bin/task-loop" specs/<NNN-feature>/tasks.md # from a normal shell--dry-run prints the plan; tasks_lint.py specs/<NNN-feature>/tasks.md checks the task lines first.
Agent (.claude/agents/) | Use it |
tdd-guide | Untagged tasks: one task, failing test first, then the code |
build-error-resolver | The build, type check or format gate fails: the smallest fix, no refactoring |
security-reviewer | Before a pull request that touches auth, input, secrets, dependencies or integrations. Reports only |
lead-engineer, software-architect, database-engineer, devops-engineer | Plans, designs, schemas, pipelines |
product-manager, ux-designer, researcher | Specs, flows, evidence |
Commits are Conventional Commits with no co-author or AI attribution (the commit-msg hook checks;
.armature/config.json sets the subject limit and a task-id prefix). Never commit .env files, secrets or client
data (the pre-commit hook checks; .armature/allow-data lists data that may be committed).
<!-- armature:core:end -->Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

