Agent Experience

Каждое демо на этой странице работает вживую с теми же эндпоинтами, что использует внешний агент — ничего не сымитировано. Демо-вызовы учитываются в админ-телеметрии как реальный внешний MCP-трафик.

Четыре поверхности

AGENTS.md

Один универсальный контракт в корне репозитория — стандарт, который читают более 28 инструментов.

Документация в сыром Markdown

Каждая опубликованная страница документации доступна как сырой Markdown по URL + .md, а чистый URL уважает Accept: text/markdown.

/llms.txt

Курируемая карта URL, собираемая из манифеста документации при каждом запросе — она не может разойтись с документацией или раскрыть неопубликованный документ.

Инструменты MCP

Шесть read-only-инструментов по HTTP и stdio; каждая ошибка содержит конкретные следующие шаги.

Markdown для машин

fetch чистого URL документации с Accept: text/markdown перенаправляется (303 + Vary: Accept) на вариант .md; навигация браузера по тому же URL по-прежнему получает HTML.

llms.txt

Собирается при каждом запросе из опубликованного манифеста документации, с блоком инструкций в стиле Stripe, исправляющим устаревшие представления модели прямо при загрузке.

Самокорректирующиеся ошибки

Ошибки реестра заканчиваются машиночитаемым трейлером «## Next actions» — названный следующий вызов восстанавливает агента гораздо лучше прозы. Транспортные ошибки намеренно остаются без него.

Цикл validate_snippet

Проверка конвенций в цикле: отправьте сниппет, примените исправления, отправьте снова — пока не станет чисто. Findings — это успешный результат; ошибкой считается только пустой или слишком длинный ввод.

Язык

Точный запрос, который отправляет агент

POST /api/mcp/public

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

AGENTS.md

Универсальный контракт для не-Claude-агентов, отдаваемый прямо из корня репозитория на этапе сборки. Намеренно минимальный — правда о стеке живёт в /docs, а не здесь.

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 Витрины

Думаете, этот паттерн можно сделать лучше? Расскажите как.

Оставить отзыв