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

Run tooling inside the `v10r` Podman container.
Never run package managers on the host; keep `package.json` and `bun.lock` synchronized.

```bash
podman compose up -d                 # start local development on :5173
podman exec v10r bun run build       # production build
podman exec v10r bun run test        # Vitest suites
podman exec v10r bun run lint        # Biome checks
podman exec v10r bun run validate    # authoritative gate
```

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 `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 Pull Requests

History mixes informal subjects with `feat(scope):` and `refactor(scope):`; prefer
descriptive subjects. PRs should explain behavior, link relevant issues,
report validation, and include screenshots for UI changes.

Preserve uncommitted work. Never stage, commit, push, stash, or reset without explicit
instruction. Run a `vr` command only when specifically requested; `vr ship` deploys.

← Back to Showcases

Geht dieses Pattern noch besser? Sag uns, wie.

Feedback geben