Nastavení harness pro AI-agenty v projektu

Struktura projektu pro efektivní práci AI agentů

AI agenty vyžadují jasnou strukturu projektu pro autonomní provoz. Nastavení harnessu jim umožňuje pochopit architekturu, spouštět testy a interagovat s prostředím bez opakovaných pokynů. Tyto principy platí pro Claude Code, Cursor i další nástroje.

Základní nastavení pravidel

Začněte jedním souborem v kořenu projektu – CLAUDE.md nebo podobný pro váš agenta. Popište strukturu adresářů, klíčové příkazy a obecná pravidla vývoje. Vyhněte se detailním pokynům k implementaci: kód je samotnou dokumentací.

Příklad základního souboru:

## Struktura
├── src/           — kód služby
├── tests/         — testy
├── migrations/    — alembic migrace
└── notebooks/     — ad-hoc skripty

## Příkazy
- Testy: `pytest tests/ -x`
- Linter: `ruff check . --fix`
- Migrace: `alembic upgrade head`
- Spuštění: `docker compose up`

Toto nastavení eliminuje nutnost opakovaných vysvětlení architektury a rutiny. Pravidla kódu ověřujte skripty, nikoli textovými pokyny.

Při chybách agenta analyzujte kontext. Pokud agent duplikuje metody nebo umísťuje třídy špatně, přidejte modulární soubory pravidel.

something-cool/
├── CLAUDE.md                          # obecná pravidla
├── src/
│   ├── auth/
│   │   ├── CLAUDE.md                  # pravidla SSO
│   │   └── ...
│   ├── billing/
│   │   ├── CLAUDE.md                  # mutace přes kontrakty
│   │   └── ...

Příznaky nedostatečného nastavení:

• Agent ručně hledá moduly.
• Doplňuje základní chyby v závislostech nebo registraci.

Integrace s prostředím prostřednictvím skills

Agenty pracují nejen s kódem, ale také s logy, metrikami, databázemi. Použijte skills pro externí služby: popište funkce a poskytněte skripty.

Struktura skills:

.claude/
└── skills/
    ├── logs/
    │   ├── SKILL.md
    │   └── search_logs.py
    ├── metrics/
    │   ├── SKILL.md
    │   └── query_grafana.py
    ├── database/
    │   ├── SKILL.md

Příklad SKILL.md pro logy:

---
name: logs
description: Hledání a analýza logů aplikace
allowed-tools: Bash, Read
---

Pro hledání logů použij skript:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"

Agent nyní sám sbírá analýzu a diagnostikuje problémy.

Kompatibilita mezi repozitáři a týmy

Pro sdílení skills mezi projekty použijte veřejné marketplaces nebo interní řešení. Tím snížíte bariéru pro kolegy.

Problém různých agentů v týmu řeší rulesync – CLI nástroj generuje instrukční soubory pro více než 25 nástrojů z jediného zdroje.

Struktura pravidel rulesync:

.rulesync/rules/
├── overview.md          # root: true
├── auth.md              # globs: ["src/auth/**"]
└── billing.md           # globs: ["src/billing/**"]

Soubory ve formátu Markdown s frontmatter:

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Pravidla pro práci s SSO
---
Pravidla

Generování:

• rulesync generate --targets "claudecode"
• rulesync generate --targets "cursor"
• rulesync generate --targets "copilot"

Výsledek: soubory CLAUDE.md, .cursorrules, copilot-instructions.md na správných místech.

Pozadové agenty pro kontrolu

Přidejte pozadové kontroly stylu, struktury a mrtvého kódu:

claude -p "Zkontroluj styl: pojmenování, struktura, mrtvý kód" \
  --allowedTools "Read,Grep,Glob"

To automatizuje revize.

Co je důležité

• Modulární pravidla: CLAUDE.md v podsložkách pro kontext.
• Skills pro prostředí: skripty + pokyny pro logy, metriky, databáze.
• Rulesync: jednotný zdroj pro multi-agent podporu.
• Evoluce: doplňujte pravidla postupně podle chyb.
• Minimalismus: pouze struktura, příkazy, bez detailů implementace.

— Editorial Team