shipfox
AGENTS.md87 starsChanged 12 days agoMITView on GitHub
CLAUDE.md is a compatibility alias for this file. - Use mise-managed tools. Prefix non-interactive commands with mise exec --. - Inspect the relevant files and local instructions before editing. Preserve unrelated user changes. - Keep changes focused on the requested task. Do not change generated output, dependencies, versions, or release metadata unless the task requires it. - Validate the changed package and its dependents before widening validation: - Report the files changed, validation run, and any skipped checks or remaining…
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 31,439 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 repository11 other files it gives its agents.
- address-pr-commentsSkill
- commitSkill
- fix-ciSkill
- generate-changesetSkill
- impeccableSkill
- implement-issueSkill
- prSkill
- readme-writerSkill
- shipSkill
- impeccableSkill
- impeccableSkill
The file
We split this AGENTS.md into the rules it gives an agent
3 rules. About 0 are common, 2 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- could be automatic: a setting could enforce it
- Very specific: line 7
Use mise-managed tools. Prefix non-interactive commands with mise exec --.
- Distinctive: line 10
Keep changes focused on the requested task.
- Distinctive: line 23
Read the linked source before making the matching change.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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
Agent guidelines
CLAUDE.md is a compatibility alias for this file.
Execution baseline
- Use mise-managed tools. Prefix non-interactive commands with
mise exec --. - Inspect the relevant files and local instructions before editing. Preserve unrelated user changes.
- Keep changes focused on the requested task. Do not change generated output, dependencies, versions, or release metadata unless the task requires it.
Validate the changed package and its dependents before widening validation:
turbo <task> --filter=@shipfox/<package>...- Report the files changed, validation run, and any skipped checks or remaining risks.
Read before editing
Read the linked source before making the matching change. For a task not listed here, use the full engineering documentation map.
| Before editing when the task... | Read | It owns |
| Needs local tasks, service recovery, shared Ollama, or affected-package checks. | Local development and release workflow | Shared local-development and validation steps. |
| Changes a published package or prepares a release. | Changesets and publishing workflow | Changeset rules, version bumps, summaries, and publishing. |
| Adds, updates, or exempts a dependency. | Dependency version policy | Version rules, exceptions, package families, and dependency checks. |
| Adds or changes a backend module, DTO, outbox event, HTTP boundary, or server package dependency. | Backend architecture | The current backend module model and package-boundary rules. |
| Adds or changes a table, migration, database query, foreign key, or transaction. | Database boundary policy | Database ownership, access, naming, migration, and enforcement rules. Run mise exec -- pnpm check:api-database-boundaries and mise exec -- pnpm check:api-migrations locally. |
| Changes client state, API adapters, or feature boundaries. | Client architecture | The current client model and architecture checks. |
| Adds or changes a client form. | Client form guidance | Form state, validation, fields, server errors, and saved drafts. |
| Adds or changes an environment variable, validator, or environment description. | Configuration policy | Configuration ownership, validation, and description rules. |
| Adds a domain or provider error, translates a request failure, or reports an unexpected failure. | Error handling | The error model, client translation, and reporting boundaries. |
| Adds a metric or changes instrumentation startup, naming, units, or labels. | Observability | The metrics model and cardinality constraints. |
| Mints, verifies, or carries an authentication token. | Auth security model | Token authority, lifetime, trust boundaries, and logging constraints. |
| Adds or changes unit tests or Storybook stories. | Testing guide | Test levels and Storybook rules. |
| Adds or changes a visual test. | Visual regression guidance | Argos builds, screenshots, and review. |
| Adds or changes end-to-end coverage. | E2E guide | E2E suite structure, setup, screens, and package boundaries. |
| Creates or changes a visual or interaction decision. | Design system | Shared design guidance; code owns exact token and component values. |
| Writes engineering prose or a runbook. | Writing guide | Repository prose, style, punctuation, and readability. |
| Adds or changes a prose rule. | ADR 0010 | The rationale, rule sources, enforcement model, and accepted divergences behind the prose standard. |
| Creates or updates a package README. | Package README standard | Required sections, public API, local checks, and license. |
| Writes product or self-hosting documentation. | Docs writing guide | Product-documentation page types, templates, and terminology. |
| Writes or reviews code comments, module exports, or non-trivial control flow. | Code style policy | Shared code-comment, import and export, and control-flow rules. |
| Adds, moves, or debugs an architecture validation rule. | Architecture validation guide | Tool selection, rule placement, cross-repository policy, fixtures, and verification. |
| Changes a cross-package client composition seam, server module boundary, or shared server-package boundary. | Engineering documentation map | The applicable ADR and its decision boundary. |
| Changes repository documentation structure or adds a shared documentation surface. | ADR 0005 | Documentation ownership, routing, and progressive disclosure. |
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.