Agent Legibility

AGENTS.md

Give Agents concise maps, not encyclopedias

Coding Agents Cheatsheet.pdf
Keep [AGENTS.md] short (< 100 lines) and progressively disclose through references.

# CLAUDE.md

<2-line overview>

## Scripts
npm run dev          # Start dev server
npm run lint         # Check for linting issues
npm run typecheck    # Verify type safety

Always run `npm lint && npm typecheck` after code changes.

See `package.json` for the full list of NPM tasks.

## Structure
- `app/`  - Application
- `docs/` - Markdown files
- `db/`   - DB migration
- `config.ts` - Global configuration

## Further Reading

**IMPORTANT:** From the docs below, read the ones required by the current task

- `docs/ssr-gotchas.md`
- `docs/testing-strategy.md`
- `docs/analytics.md`

Treat docs as source code

docs/
├── decisions/          # Strategic decisions (ADRs)
│   ├── db-sharding.md
│   └── i18n.md
├── user-flows/         # Sequence diagrams, flow diagrams
│   ├── checkout-flow.md
│   └── signin-flow.md
├── plans/
│   └── active/
│		└── featureA    # Ralph Wiggum / ralph-tui ready
│			├── prd.md
│			├── prompt_plan.md
│			├── prompt_impl.md
│			├── plan.md
│			├── specs/
│				├── topicA.md
│				├── topicB.md
│				└── ...
│   └── completed/
├── references/         # Slowly changing material referenced by other parts
│   ├── compliance.md
│   ├── accessibility.md
│   ├── performance.md
│   └── ...
├── AGENTS.md
└── ARCHITECTURE.md

Provide observability skills

Screenshot skills
Chrome Devtools Protocol
Local observability stack (Logs, OTel)

Design <> Code

Use Design tokens: primitive/semantic/component + alias
Connect Figma components to code Prefer Code Connect CLI and make it part of your CI pipeline.

Agent distribution

Team-level rules, skills and connectors on Claude, Codex and Cursor
Packmind
Git submodule with an install.sh script. Use symlinks for cross-agent compatibility similar to skills
Run your own Plugin Marketplace for Claude Code.Plugin = Skills + Agents + Hooks + MCP servers