agentleFS
alexmmatosalexmmatos/arthur-mcp/AGENTS.md

arthur-mcp

AGENTS.md2 starsChanged 4 months agoMITView on GitHub

This file is the shared project memory for Codex, Claude Code, and any other development agent. Before changing code, read this file, docs/ROADMAP.md, and docs/HANDOFF.md. Arthur MCP is a full-stack application for managing MCP servers/projects, importing API definitions, generating dynamic tools, handling prompts, secrets, logs, settings, sharing, and documentation. Before working: While working:

  • Installs packages
  • 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 33,315 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 repository3 other files it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

30 rules. About 0 are common, 15 are distinctive, and 15 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈15

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 15

    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
  1. Very specific:

    Run frontend + backend in development: npm run dev

    line 42
  2. Very specific:

    Run frontend only: npm run start

    line 43
  3. Very specific:

    Run backend only: npm run start:dev --prefix api

    line 44
  4. Very specific:

    Check frontend file organization: npm run check:frontend-structure

    line 47
  5. Very specific:

    Test backend with coverage gate: npm run test:cov --prefix api -- --runInBand

    line 52
  6. Very specific:

    Run backend e2e tests: npm run test:e2e --prefix api

    line 53
  7. Very specific:

    Read AGENTS.md, docs/ROADMAP.md, and docs/HANDOFF.md.

    line 59
  8. Distinctive:

    If another person's changes affect files you need to edit, read them and work with them.

    line 65
  9. Distinctive:

    Keep the scope small and aligned with the current task.

    line 66
  10. Distinctive:

    Prefer existing repository patterns.

    line 70
  11. Distinctive:

    Avoid broad refactors when the task is focused.

    line 72
  12. Distinctive:

    Treat permissions as part of every new feature, not as follow-up work.

    line 73
  13. Distinctive:

    Update tests when changing meaningful behavior.

    line 74
  14. Distinctive:

    Update the relevant documentation in the same change whenever behavior, architecture, entities, flows, commands, infrastructure, agents, or …

    line 75
  15. Very specific:

    All database schema or data-shape changes must be implemented through migrations.

    line 76
  16. Distinctive:

    Do not change local database files, lockfiles, or deploy configuration unless there is a clear reason.

    line 77
  17. Very specific:

    If you change frontend code, validate with at least npm run type-check or npm test when practical.

    line 78
  18. Very specific:

    If you change backend code, validate with at least npm test --prefix api or a focused test when practical.

    line 79
  19. Very specific:

    When adding a permission, update the backend RolePermissions contract, backend built-in role presets, frontend Permission enum, frontend …

    line 85
  20. Very specific:

    Do not ship a new page, tab, create/edit/delete action, integration, credential surface, or settings panel without explicitly documenting …

    line 87
  21. Very specific:

    Update docs/ROADMAP.md if task state changed.

    line 93
  22. Distinctive:

    Update every affected reference document, or explicitly state that no other documentation was affected.

    line 94
  23. Distinctive:

    Every code or configuration change must include a documentation check.

    line 100
  24. Distinctive:

    Update these files when the related area changes:

    line 102
  25. Very specific:

    If a change affects user-facing flows, add or update the relevant flow documentation before finishing.

    line 116
  26. Distinctive:

    Before finalizing, agents must answer the documentation check internally:

    line 118
  27. Distinctive:

    If yes, which documentation file was updated?

    line 122
  28. Distinctive:

    If no documentation update was needed, why not?

    line 123
  29. Distinctive:

    When Codex is working on an area covered by one of these specialists, use the specialist description as guidance and preserve any …

    line 160
  30. Very specific:

    When switching between Codex and Claude Code, start the session with: "Read AGENTS.md, docs/ROADMAP.md, docs/HANDOFF.md, and …

    line 169

≈ “Common” is an estimate: at least 1 in 5 of the 42,283 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md

This file is the shared project memory for Codex, Claude Code, and any other development agent. Before changing code, read this file, docs/ROADMAP.md, and docs/HANDOFF.md.

Product

Arthur MCP is a full-stack application for managing MCP servers/projects, importing API definitions, generating dynamic tools, handling prompts, secrets, logs, settings, sharing, and documentation.

Stack

  • Frontend: React 18, TypeScript, Vite, Material UI, React Router, Axios, react-i18next/i18next, Vitest.
  • The current frontend design is desktop-first, not mobile-first; responsive/mobile adaptation is pending work tracked in docs/ROADMAP.md. New UI should not make this worse, and mobile work goes through the mobile-first-expert specialist.
  • Backend: NestJS, TypeScript, TypeORM, local SQLite, Mongo/Mongoose in parts of the domain, JWT/Passport, Jest.
  • Local runtime: frontend at the repository root and API in api/.
  • Deploy/infra: Dockerfile, docker-compose.yml, nginx.conf, and render.yaml.

Structure

  • src/: React frontend.
  • src/pages/: main application screens.
  • src/components/: reusable components.
  • src/context/: React contexts, including auth, terminology, and server navigation.
  • src/i18n.ts: frontend i18next initialization and language detection.
  • src/locales/: frontend translation resources by locale and namespace.
  • src/theme/: theme and color mode.
  • api/src/: NestJS backend.
  • api/src/auth/: authentication, JWT, and password reset.
  • api/src/dynamic-mcp/: dynamic MCP tool generation/execution from APIs.
  • api/src/swagger/: Swagger/OpenAPI project import and persistence.
  • api/src/prompts/, api/src/secrets/, api/src/settings/, api/src/users/, api/src/roles/: domain modules.
  • api/src/audit-logs/ and api/src/execution-logs/: audit trails and execution history.
  • api/src/observability/: operational health checks, structured logging, Prometheus metrics, correlation IDs, and OpenTelemetry tracing.
  • observability/: local Prometheus, Grafana, and Tempo helper configuration.
  • docs/ENTITIES.md: backend domain entity reference across SQLite/TypeORM and MongoDB/Mongoose.
  • docs/DESIGN_PATTERNS.md: backend and frontend architecture/design pattern reference.
  • docs/FLOWS.md: user-facing workflow notes and API/UI behavior that affects journeys.

Commands

  • Install frontend dependencies: npm install
  • Install backend dependencies: npm install --prefix api
  • Run frontend + backend in development: npm run dev
  • Run frontend only: npm run start
  • Run backend only: npm run start:dev --prefix api
  • Build frontend: npm run build
  • Type-check frontend: npm run type-check
  • Check frontend file organization: npm run check:frontend-structure
  • Validate static template catalogs: npm run check:template-catalogs
  • Test frontend: npm test
  • Build backend: npm run build --prefix api
  • Test backend: npm test --prefix api
  • Test backend with coverage gate: npm run test:cov --prefix api -- --runInBand
  • Run backend e2e tests: npm run test:e2e --prefix api

Agent Protocol

Before working:

  1. Read AGENTS.md, docs/ROADMAP.md, and docs/HANDOFF.md.
  2. Run git status --short.
  3. Review .claude/agents/README.md when the task overlaps with a Claude Code specialist area.
  4. Review docs/ENTITIES.md when the task touches backend domain data or persistence.
  5. Review docs/DESIGN_PATTERNS.md when the task changes backend architecture, frontend architecture, state management, routing, data access, UI composition, or shared conventions.
  6. Identify uncommitted changes and do not revert them unless explicitly asked.
  7. If another person's changes affect files you need to edit, read them and work with them.
  8. Keep the scope small and aligned with the current task.

While working:

  • Prefer existing repository patterns.
  • Keep frontend contracts in individual name.kind.ts files, focused utilities one responsibility per file, hooks in .hook.ts, and React-rendering modules in matching named .tsx files. Named source files export exactly one symbol; only index.ts aggregates exports; every directory under src/ contains index.ts and index.css. npm run type-check enforces these conventions.
  • Avoid broad refactors when the task is focused.
  • Treat permissions as part of every new feature, not as follow-up work. Any new user-facing surface, route, action, API endpoint, integration, or settings panel must either reuse an existing permission intentionally or add a new permission end-to-end.
  • Update tests when changing meaningful behavior.
  • Update the relevant documentation in the same change whenever behavior, architecture, entities, flows, commands, infrastructure, agents, or project conventions change.
  • All database schema or data-shape changes must be implemented through migrations. Do not rely on TypeORM synchronize, manual local database edits, or implicit startup sync for database changes.
  • Do not change local database files, lockfiles, or deploy configuration unless there is a clear reason.
  • If you change frontend code, validate with at least npm run type-check or npm test when practical.
  • If you change backend code, validate with at least npm test --prefix api or a focused test when practical.

Permission gate for new features:

  1. Decide the permission model before implementing the feature UI/API.
  2. Reuse an existing permission only when the feature is genuinely covered by that permission's domain and risk.
  3. When adding a permission, update the backend RolePermissions contract, backend built-in role presets, frontend Permission enum, frontend UserPermissions, frontend role fallback presets, affected route/action guards, tests, and documentation.
  4. Backend guards/decorators are authoritative for protected API behavior; frontend can(Permission.X) checks are required for navigation, disabled states, hidden actions, and permission-specific empty/restricted states.
  5. Do not ship a new page, tab, create/edit/delete action, integration, credential surface, or settings panel without explicitly documenting its permission decision.
  6. Operational endpoints /health, /ready, /live, and /metrics are intentionally public because they are infrastructure probes/scrape targets and do not mutate user data.

After finishing:

  1. Update docs/HANDOFF.md.
  2. Update docs/ROADMAP.md if task state changed.
  3. Update every affected reference document, or explicitly state that no other documentation was affected.
  4. Report which validation commands were run and their result.
  5. Make the recommended next step clear.

Documentation Gate

Every code or configuration change must include a documentation check. Documentation is part of the deliverable, not a follow-up task.

Update these files when the related area changes:

  • AGENTS.md: project structure, commands, conventions, agent protocol, shared context rules, or available Claude Code specialists.
  • docs/ROADMAP.md: priorities, task status, decisions, open questions, or completed work.
  • docs/HANDOFF.md: every completed work session.
  • docs/ENTITIES.md: backend entities, fields, persistence behavior, repository contracts, or domain data rules.
  • docs/DESIGN_PATTERNS.md: backend/frontend design patterns, architecture, state management, routing, data access, UI composition, validation, or testing conventions.
  • docs/FLOWS.md: user-facing flow changes, permission-sensitive UI behavior, onboarding, or error/loading states.
  • src/locales/: user-facing copy changes, translation namespace additions, or supported locale changes.
  • .claude/agents/README.md: Claude Code agent additions, removals, renames, or routing changes.
  • Specialist files in .claude/agents/: agent-specific behavior, scope, tools, or instructions.

Project documentation, source comments, code identifiers, and translation keys must stay in English. Locale values under src/locales/<locale>/ are the only expected exception and should contain the target-language user-facing translations.

If a change affects user-facing flows, add or update the relevant flow documentation before finishing. If no dedicated flow document exists yet, create one under docs/ or record the gap in docs/ROADMAP.md.

Before finalizing, agents must answer the documentation check internally:

  • Did the change alter behavior, data, commands, setup, deployment, UI flow, permissions, or agent workflow?
  • Did every new feature, endpoint, page, tab, action, and settings/control surface make an explicit permission decision and update backend/frontend permission definitions if needed?
  • If yes, which documentation file was updated?
  • If no documentation update was needed, why not?

Claude Code Agents

Claude Code has specialist agent definitions in .claude/agents/. These files are part of the shared development context and should be kept in English.

Index:

  • .claude/agents/README.md: quick index of available Claude Code specialists.

Known specialists:

  • backend-test-engineer: backend Jest tests for NestJS services, controllers, guards, repositories, DTO validation, persistence behavior, and API/e2e flows.
  • cloud-expert: cloud architecture across AWS, GCP, and Azure, including security, cost, managed databases, and Well-Architected practices.
  • compliance-counsel: software license review, dependency obligations, attribution, distribution risk, contributor policies, and compliance/legal notes.
  • developer-advocate: developer quickstarts, demos, examples, launch content, DX reviews, and community feedback loops.
  • devops-expert: CI/CD, GitHub Actions, deploy automation, infrastructure scripts, monitoring, logging, and operational best practices.
  • docker-compose-expert: Docker Compose environments, networks, volumes, service dependencies, environment variables, and healthchecks.
  • docker-expert: Dockerfiles, multi-stage builds, minimal images, container security, and production container best practices.
  • frontend-test-engineer: frontend Vitest and React Testing Library tests for React pages, feature components, hooks, API client behavior, routing, permissions, i18n, forms, and user-visible flows.
  • gof-expert: Gang of Four design pattern selection, naming, refactoring, and misuse review.
  • mobile-first-expert: responsive/mobile-first layouts, small-screen adaptation of pages and components, touch targets, breakpoint behavior, and mobile usability fixes.
  • nestjs-expert: NestJS backend modules, controllers, services, DTOs, guards, interceptors, persistence, authentication, and Jest tests.
  • oss-scout: open source tool/library discovery, maturity review, comparisons, and project health research.
  • product-owner: user stories, acceptance criteria, backlog prioritization, MVP scope, requirements, and product documentation.
  • react-frontend-engineer: React/TypeScript frontend implementation, Feature-Driven Architecture, Atomic Design, barrel exports, hooks, forms, routes, state, API integration, i18n, and frontend tests.
  • render-expert: Render.com services, render.yaml, environment variables, managed databases, health checks, and production deployments.
  • software-architect: architecture, module boundaries, data modeling, integration strategy, cross-cutting patterns, and technical roadmap decisions.
  • software-engineer: full-stack implementation, debugging, refactoring, testing, and documentation updates across frontend and backend.
  • solid-expert: SOLID responsibility boundaries, interface design, dependency direction, substitutability, and maintainability review.
  • system-tutor: user-facing tutorials, walkthroughs, section guides, onboarding paths, and product explanations for Arthur MCP.
  • ui-expert: React, TypeScript, and MUI interface creation, redesign, and review using the project's "openclaw" style with Feature-Driven Architecture, Atomic Design, and controlled barrel exports.
  • ux-analyst: user journeys, usability audits, onboarding friction, empty/error/loading states, and user-facing flow analysis across pages, features, and shared UI conventions.
  • vercel-expert: Vercel frontend/API deployment, vercel.json, environment variables, preview deployments, domains, and GitHub integration.
  • tool-instructor: user-facing copy for Arthur MCP — tooltips, helper text, empty states, error messages, onboarding guides, and in-app documentation.
  • naming-expert: naming variables, functions, types, components, routes, API endpoints, DB columns, MCP tool/resource/prompt names, and UI labels across the full stack.

When Codex is working on an area covered by one of these specialists, use the specialist description as guidance and preserve any domain-specific constraints documented there. If Claude Code agents are added, renamed, or removed, update both this section and .claude/agents/README.md.

Continuity Conventions

  • AGENTS.md contains stable project information.
  • docs/ROADMAP.md contains priorities, tasks, and macro status.
  • docs/HANDOFF.md contains the latest handoff.
  • Documentation must stay in sync with code and configuration changes.
  • Small commits with clear messages help any agent resume context.
  • When switching between Codex and Claude Code, start the session with: "Read AGENTS.md, docs/ROADMAP.md, docs/HANDOFF.md, and .claude/agents/README.md, run git status --short, and continue from the current state."

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.