Konfiguracja harness dla agentów AI w projekcie

Struktura projektu dla skutecznej pracy agentów AI

Agentom AI potrzebna jest jasna struktura projektu, by działać autonomicznie. Konfiguracja harness pozwala im rozumieć architekturę, uruchamiać testy i interakcje z środowiskiem bez ciągłych wskazówek. Zasady te są uniwersalne dla narzędzi takich jak Claude Code, Cursor czy innych.

Podstawowa konfiguracja reguł

Zacznij od jednego pliku w katalogu głównym projektu — CLAUDE.md lub odpowiednika dla Twojego agenta. Opisz strukturę katalogów, kluczowe polecenia oraz zasady tworzenia kodu. Unikaj szczegółowych instrukcji implementacyjnych: kod sam w sobie jest dokumentacją.

Przykład podstawowego pliku:

## Struktura
├── src/           — kod serwisu
├── tests/         — testy
├── migrations/    — migracje alembic
└── notebooks/     — skrypty ad-hoc

## Polecenia
- Testy: `pytest tests/ -x`
- Linter: `ruff check . --fix`
- Migracje: `alembic upgrade head`
- Uruchomienie: `docker compose up`

Taka konfiguracja eliminuje potrzebę powtarzania wyjaśnień architektury i rutyn. Standardy kodu sprawdzaj za pomocą skryptów, a nie dokumentacji.

W przypadku błędów agenta analizuj kontekst. Jeśli agent powtarza metody lub umieszcza klasy niepoprawnie, dodaj modułowe pliki reguł.

something-cool/
├── CLAUDE.md                          # ogólne zasady
├── src/
│   ├── auth/
│   │   ├── CLAUDE.md                  # zasady SSO
│   │   └── ...
│   ├── billing/
│   │   ├── CLAUDE.md                  # modyfikacje przez kontrakty
│   │   └── ...

Oznaki niedokończonej konfiguracji:

• Agent szuka modułów ręcznie.
• Dopuszcza podstawowe błędy w zależnościach lub rejestracji.

Integracja z środowiskiem poprzez skills

Agenty działają nie tylko z kodem, ale też z logami, metrykami i bazami danych. Wykorzystuj skills do usług zewnętrznych: opisz funkcje i dostarcz skrypty.

Struktura skills:

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

Przykład pliku SKILL.md dla logów:

---
name: logs
description: Wyszukiwanie i analiza logów aplikacji
allowed-tools: Bash, Read
---

Aby wyszukać logi, użyj skryptu:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"

Teraz agent samodzielnie zbiera analizę i diagnozuje problemy.

Zgodność między repozytoriami i zespołami

Do wymiany skills między projektami wykorzystaj publiczne marketplaces lub rozwiązania wewnętrzne. To obniża próg wejścia dla kolegów.

Problem różnorodnych agentów w zespole rozwiązuje rulesync — narzędzie CLI generujące pliki instrukcji dla ponad 25 narzędzi z jednego źródła.

Struktura reguł rulesync:

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

Pliki w formacie Markdown z frontmatter:

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Zasady pracy z SSO
---
Zasady

Generowanie:

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

Wynik: pliki CLAUDE.md, .cursorrules, copilot-instructions.md w odpowiednich lokalizacjach.

Agenty tła do kontroli

Dodaj tło sprawdzające styl, strukturę i martwy kod:

claude -p "Sprawdź styl: nazewnictwo, struktura, martwy kod" \
  --allowedTools "Read,Grep,Glob"

To automatyzuje przegląd kodu.

Co ważne

• Modułowe reguły: CLAUDE.md w podkatalogach dla lepszego kontekstu.
• Skills dla środowiska: skrypty + instrukcje dla logów, metryk, bazy danych.
• Rulesync: jedno źródło dla wsparcia wieloagentowe.
• Ewolucja: uzupełniaj reguły w miarę pojawiania się błędów.
• Minimalizm: tylko struktura, polecenia, bez szczegółów implementacji.

— Editorial Team