Agent Experience

Jede Demo auf dieser Seite läuft live gegen dieselben Endpunkte, die ein externer Agent nutzt — nichts ist simuliert. Demo-Aufrufe zählen in der Admin-Telemetrie als echter externer MCP-Traffic.

Vier Oberflächen

AGENTS.md

Ein universeller Vertrag im Repo-Root — der Standard, den über 28 Coding-Tools lesen.

Roh-Markdown-Doku

Jede veröffentlichte Doku-Seite liefert unter URL + .md rohes Markdown, und die saubere URL respektiert Accept: text/markdown.

/llms.txt

Eine kuratierte URL-Karte, bei jeder Anfrage aus dem Doku-Manifest gebaut — sie kann weder driften noch ein unveröffentlichtes Dokument leaken.

MCP-Tools

Sechs Read-only-Tools über HTTP und stdio; jeder Fehler enthält konkrete nächste Schritte.

Markdown für Maschinen

Ein fetch einer sauberen Doku-URL mit Accept: text/markdown wird per 303 + Vary: Accept auf die .md-Variante umgeleitet; ein Browser, der dieselbe URL ansteuert, erhält weiter HTML.

llms.txt

Bei jeder Anfrage aus dem veröffentlichten Doku-Manifest gebaut, mit einem Instruktionsblock im Stripe-Stil, der veraltete Modellannahmen direkt beim Abruf korrigiert.

Selbstkorrigierende Fehler

Registry-Fehler enden mit einem maschinenlesbaren „## Next actions“-Trailer — ein benannter nächster Aufruf hilft einem Agenten deutlich besser als Prosa. Transport-Fehler bleiben bewusst nackt.

Die validate_snippet-Schleife

Der Konventionsprüfer zum Loopen: Snippet einreichen, Fixes anwenden, erneut einreichen, bis es sauber ist. Findings sind ein Erfolgsergebnis — nur leere oder überlange Eingaben sind ein Fehler.

Sprache

Der exakte Request, den ein Agent sendet

POST /api/mcp/public

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "validate_snippet",
    "arguments": {
      "snippet": "<your snippet>",
      "language": "svelte"
    }
  }
}

AGENTS.md

Der universelle Vertrag für Nicht-Claude-Agenten, zur Build-Zeit direkt aus dem Repo-Root serviert. Bewusst minimal — die Stack-Wahrheit lebt in /docs, nicht hier.

AGENTS.md

# Repository Guidelines

Velociraptor (v10r) is a SvelteKit pattern library for adaptation. Claude Code follows
[CLAUDE.md](CLAUDE.md).

## Project Structure

- `src/routes/`: localized pages under `[[locale=locale]]/`; REST/SSE under `api/`.
- `src/lib/components/`: reusable UI; `src/lib/state/`: shared rune state.
- `src/lib/server/`: domains, database schemas/access, and integrations.
- `static/`: assets; `content/`: authored content; `messages/`: translations.
- `pattern-library/`: canonical registry; `mcp/`: stdio transport; `scripts/`: tooling.

## Development and Validation

Claude Code cloud sessions are the default place to develop: no container, no secrets,
commands run directly (`bun run validate`). Local sessions run tooling inside the `v10r`
Podman container. What runs where, and what to report as not run:
[development-environment.md](docs/foundation/development-environment.md).
Never run package managers on the host; keep `package.json` and `bun.lock` synchronized.

```bash
bun run validate                     # authoritative gate (cloud)
bun run validate:build               # + production build and perf ratchet
podman compose up -d                 # local: start development on :5173
podman exec v10r bun run validate    # local: the same gate in the container
```

The gate includes typechecking, Biome, tests, registry/excerpts, i18n/content, and quality
checks. No CI pipeline exists. Report failures accurately.

## Architecture and Coding Style

Keep domains framework-free; adapters own HTTP responses, redirects, and date
serialization. Never import `#lib/server/` into `.svelte` or universal `+page.ts`.
Change code directly: no compatibility layers, migration shims, or deprecation paths.

Follow `biome.json`: tabs, LF, 120-column width, single JS quotes, semicolons, trailing
commas. Use PascalCase components, kebab-case modules, and `.svelte.ts` for runes.
Consult [docs/naming.md](docs/naming.md) before introducing names; comments explain why —
the principle behind both is [docs/foundation/self-expressive-project.md](docs/foundation/self-expressive-project.md).
Never name a prop `state`.

Use existing components instead of raw buttons, inputs, selects, or textareas.
Exceptions: hidden inputs, table-row checkboxes, numeric selects, and specially styled
interactive regions. Colors use `src/app.css` tokens.

## Testing

Co-locate Vitest `*.test.ts`; database tests use `*.pglite.test.ts` and PGlite.
Run one file with `bunx vitest run <path>` (locally: `podman exec v10r bunx vitest run <path>`).
MCP uses `bun:test` (`test:mcp`). Test invariants, security, and regressions; verify UI
through browser showcases. No coverage threshold is configured.

## Documentation and Generated Files

Start at [docs/README.md](docs/README.md); navigate directory READMEs before topics.
Never grep blindly through `docs/`. Read `docs/codebase-organization.md` and
`docs/system-abstraction.md` for architecture. Reference canonical sources; avoid duplicate
stack documentation.

Never hand-edit generated pattern pages, Paraglide output, MCP excerpts, or retrieval
indexes. Use `package.json` generators; `refresh` also ingests docs into
the database. See [mcp/README.md](mcp/README.md) for machine-readable access.

## Commits and Branches

History mixes informal subjects with `feat(scope):` and `refactor(scope):`; prefer
descriptive subjects that explain behavior.

Work on a feature branch: commit and push it, hand off the branch and its HEAD SHA, and stop.
No PR is needed; a PR is only the fallback vehicle of a ship. GitHub `main` moves only when
Stas explicitly says to ship in the conversation — then follow
[shipping.md](docs/stack/ops/shipping.md) (squash into `main` → GitLab sync → Vercel). Never push
`main` or GitLab, never force-push, stash, or reset. Run a `vr` command only when
specifically requested.

Name every branch you create `<agent>/<env>/<feature>`: `<agent>` is `claude` or `codex`; `<env>` is `cloud` in a cloud environment (Claude: `CLAUDE_CODE_REMOTE=true`; Codex: no `~/.codex/` directory), otherwise `local`; `<feature>` is short kebab-case. Example: `claude/local/add-login-page`. Rename an auto-named branch (`claude/brave-bohr-9jw2fq`) to this form before its first push.

← Back to Showcases

Geht dieses Pattern noch besser? Sag uns, wie.

Feedback geben