Nastavení AI agentů

Codex, Claude, Junie
Backend vývoj

Martin Peterka, 5. května 2026

---

Co od toho čekat

Nebudeme si tu nastavovat nástroj krok za krokem.

Chci, abyste po téhle hodině věděli, kde a jak agenty nastavit.

• aby méně hádali a víc se drželi TSM zvyklostí
• aby nečetli věci, které číst nemají
• aby uměli pustit správný build nebo test

Nastavení si každý udělá později sám v klidu.

---

Cíl školení

Chci, aby každý uměl odpovědět:

1. kam dát pravidla pro repo a kam osobní poznámky
2. kdy použít AGENTS.md a kdy radši skill
3. co už leží v tsm-ai-agents-settings
4. co znamená MCP server v praxi
5. Máme MS Teams skupiny

---

Proč vůbec něco nastavovat

Agent bez nastavení se chová jako nový kolega první den.

Vidí pár souborů, přečte prompt a zbytek si domyslí.

Dobré nastavení mu řekne věci, které my bereme jako samozřejmost:

• nedělat velký refactoring kvůli malému bugfixu
• u Maven multi-module projektu nepouštět celý svět zbytečně
• držet se našich Spring / Kotlin patternů
• nesahat na tajemství a lokální bordel
• zeptat se dřív, než udělá něco mimo workspace

---

Co nastavení reálně ovlivňuje

Oblast	Bez nastavení	S nastavením
Kontext	odpověď podle internetu a pár souborů	odpověď podle našeho repa
Změny v kódu	ochotně "vylepší" i okolí	drží se zadání
Testy	zkusí první příkaz, který ho napadne	ví, co pustit pro modul
Bezpečnost	může číst moc široce	narazí na ignore a approval
Nástroje	opisuje z textu	ptá se IDE, GitLabu nebo TSM MCP

---

Mentální model

uživatelský styl
        ↓
globální nastavení nástroje
        ↓
projektové AGENTS.md
        ↓
týmové sdílené instrukce
        ↓
skilly a MCP nástroje
        ↓
aktuální prompt a otevřené soubory

Když je některá vrstva prázdná, agent ji nenápadně nahradí vlastním odhadem.

Codex: EDITOR kvůli Ctrl+G

První drobnost, která ušetří nervy: nastavte si EDITOR.

Když je prompt delší než dvě věty, otevřete ho přes Ctrl+G rovnou v editoru.

---

Kde žije konfigurace Codexu

Tady končí věci, které jsou vaše:

~/.codex/
├── config.toml          osobní nastavení Codexu
├── instructions.md      globální osobní instrukce
├── skills/              uživatelské skilly
├── plugins/             nainstalované pluginy
└── ...

Kde žije konfigurace projektu

Tady naopak začínají věci, které má dostat každý, kdo repo otevře:

<repo>/
├── AGENTS.md            projektové instrukce
├── .mcp.json            projektové MCP servery
└── .aiignore            co agent nemá číst / posílat

---

Jak se skládají instrukce

@../tsm-ai-agents-settings/AGENTS.md

# <repo-name>

## Module Catalog

- `tsm-foo` — service
- `tsm-foo-client` — public client

## Build Commands

- `./mvnw -pl tsm-foo -am test`

Sdílený základ nebudeme kopírovat do každého repa ručně.

Lokální AGENTS.md má doplnit jen to, co je pro dané repo opravdu jiné.

---

AGENTS.md vs skill

Věc	Role	Příklad
AGENTS.md	dlouhodobý kontext projektu nebo týmu	styl změn, build příkazy, architektura repo
Skill	cílený návod pro konkrétní typ úkolu	testování, Flyway, code review

Do AGENTS.md dejte věci, které mají platit skoro při každém úkolu.

Do skillu dejte detailní postup, který agent potřebuje až ve správnou chvíli.

---

Týmová pravidla a osobní pravidla

Týmová pravidla jsou pro věci, na kterých se chceme shodnout:

• patří do tsm-ai-agents-settings
• popisují opakované TSM patterny
• nastavují společný základ, ne encyklopedii všeho
• mění se přes merge request

Osobní pravidla si nechte pro svůj styl práce:

• patří do osobního nastavení nástroje
• tón odpovědí
• drobné návyky, které nejsou týmová dohoda

---

Co už pokrývá AGENTS.md

V tsm-ai-agents-settings/AGENTS.md už je dost věcí, které nechceme vysvětlovat v každém promptu:

• malé cílené změny a testy pro bugfixy
• Maven multi-module layout
• Kotlin, Spring Boot, Kafka, Feign, PostgreSQL
• veřejné API a versioning
• Elasticsearch a cache patterny
• repository layer a audit konfiguraci
• testovací konvence

Není to hotové navždy.

---

Skilly: detailní instrukce podle úkolu

Skill je tahák pro konkrétní typ práce.

Agent ho nemá číst pořád. Má ho vytáhnout ve chvíli, kdy řeší daný problém.

V tsm-ai-agents-settings/skills/ už máme například:

Skill	Kdy ho použít
testing.md	MockK, AssertJ, struktura testů
entity-patterns.md	JPA entity, DTO, convertery
service-layer.md	servisní vrstva a DI
flyway.md	migrace databáze
code-review.md	review MR nebo diffu

---

Pluginy: co přidávají

Plugin berte jako balíček schopností navíc.

Typicky přidá:

• skilly
• MCP servery nebo jejich konfiguraci
• runtime podporu pro práci s dokumenty, prezentacemi, browserem
• šablony, assety nebo pomocné skripty

Plugin není naše architektura. Jen rozšiřuje nástroj, kterým s ní pracujeme.

---

Marketplace a instalace pluginů

Pluginy se dají instalovat přes marketplace.

Marketplace: jak to funguje

• marketplace: odkud se balíček bere
• plugin: co je zapnuté
• skill uvnitř pluginu: kdy se má použít konkrétní postup

Týmový skills/code-review.md je náš lokální skill mimo marketplace.

---

Bezpečnost: tajemství

Agent nesmí zbytečně číst ani posílat tajemství.

Hlídejte hlavně:

• .env, .env.*
• tokeny a API klíče
• lokální konfigurace s credentials
• exporty databází a dumpy
• produkční logy se zákaznickými daty

---

Bezpečnost: .aiignore

Minimální .aiignore, který bych v repu čekal:

.env
.env.*
*.pem
*.key
target/

Asi nám chybí. ("TODO")

---

Bezpečnost: rizikové režimy

Otázka není, jestli agentovi věříme.

Otázka je, co smí udělat bez toho, aby se někdo podíval.

Nejvíc bych brzdil:

• příliš široký přístup k filesystemu
• auto-edit mode bez kontroly
• automatické spouštění příkazů s vedlejšími efekty
• důvěřování neznámému MCP serveru

---

Příklad osobní Codex konfigurace

~/.codex/config.toml:

model = "gpt-5.5"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[mcp_servers.intellij-idea]
url = "http://127.0.0.1:64672/stream"

[mcp_servers.gitlab]
url = "https://gitlab.datalite.cz/api/v4/mcp"

Tokeny a credentials do promptu nepatří.

---

MCP: co to je

MCP je způsob, jak agentovi bezpečně půjčit nástroje.

Bez MCP jen čte soubory a hádá. S MCP se může zeptat systému, který něco opravdu ví:

• ptát se IDE na strukturu projektu
• spouštět build nebo testy
• číst GitLab merge requesty
• používat interní znalostní bázi
• pracovat s konkrétními daty přes bezpečně vystavené nástroje

Každý MCP server je zároveň nová schopnost i nová bezpečnostní hranice.

---

MCP v našem prostředí

Projektové .mcp.json:

{
  "mcpServers": {
    "tsm": {
      "type": "http",
      "url": "https://feature-mcp.k8s.datalite.cz/mcp"
    },
    "gitlab": {
      "type": "http",
      "url": "https://gitlab.datalite.cz/api/v4/mcp"
    }
  }
}

---

MCP: osobní vs projektové

Umístění	Příklad	Kdy použít
~/.codex/config.toml	IntelliJ, Context7, osobní GitLab	osobní workflow
<repo>/.mcp.json	tsm, gitlab	týmově sdílené nástroje
IDE nastavení	IntelliJ MCP server	práce přímo s projektem

Projektové MCP dejte tam, kde chceme stejný základ pro celý tým.

Osobní MCP si nechte pro věci, které má každý jinak: editor, port, token, lokální nástroj.

---

A teď živě

Teď je lepší to vidět než o tom mluvit.

Ukážeme stejný úkol s různými instrukcemi:

• W:\martin.peterka\ai-coding
• AGENTS.md
• varianty instrukcí
• stejný prompt, jiný výsledek

---

Typické chyby při práci s agenty

1. "Buď pečlivý" není instrukce
   Napište, co má udělat jinak než defaultní agent.

2. Málo kontextu
   Syntaxi trefí často. Záměr bez kontextu mine snadno.

3. Příliš dlouhá konverzace
   To, že jsme něco řešili před hodinou, neznamená, že to pořád drží správně.

4. Příliš široká oprávnění
   Je to pohodlné přesně do chvíle, než agent udělá vedlejší efekt.

---

Praktický checklist pro vývojáře

Než agentovi svěříte větší změnu:

• Mám nainstalovaný a přihlášený Codex / Claude Code.
• Mám nastavený vhodný model.
• Mám stažené tsm-ai-agents-settings.
• Vím, co se načítá z AGENTS.md.
• Vím, které MCP servery mám zapnuté.
• Nemám v kontextu tajemství.
• Podíval jsem se na možnosti git worktree.

---

Praktický checklist pro repozitář

Repo, ve kterém má agent normálně pracovat, by mělo mít:

• AGENTS.md s importem sdíleného základu
• stručný module catalog
• konkrétní build a test příkazy
• zmínku o výjimkách proti běžnému TSM stylu
• .mcp.json, pokud jsou potřeba sdílené MCP servery
• .aiignore, pokud repo obsahuje citlivé nebo velké lokální soubory

Nepíšeme román. Stačí pravidla, podle kterých se dá rozhodnout.

---

tsm-ai-agents-settings

Centrální repozitář pro sdílené instrukce AI agentů v TSM.

Proč existuje:

• TSM má mnoho backend repozitářů
• nechceme kopírovat stejné konvence všude ručně
• jeden sdílený základ se importuje do konkrétních AGENTS.md
• změny se dostanou do dalších agentických session

---

Co je v tsm-ai-agents-settings

Najdete tam hlavně:

• AGENTS.md — sdílený baseline pro backend repozitáře
• root-AGENTS.md — pravidla pro práci z W:\tsm
• skills/ — detailní postupy pro opakované úkoly
• .mcp.json — společné MCP servery tsm a gitlab
• scripts/ a hooks/ — nasazení root instrukcí

Berme to jako živý dokument. Když něco opakovaně vysvětlujeme agentům v promptu, patří to nejspíš sem.

---

Jak přispívat k týmovým pravidlům

Přidávejte pravidla, která bychom byli ochotní říct i novému vývojáři:

• opakovaně použitelná ve více repozitářích
• konkrétní a ověřitelná
• krátká
• navázaná na reálný TSM pattern
• užitečná ve chvíli, kdy se agent rozhoduje

Nepatří tam:

• detail z jednoho ticketu
• osobní preference bez týmové dohody
• pravidlo, které sami nedodržujeme

---

Co si odnést

Nastavení agentů není papírování kolem nástroje.

Je to způsob, jak z náhodného pomocníka udělat někoho, kdo zná naše mantinely.

1. týmová pravidla patří do tsm-ai-agents-settings
2. osobní pravidla patří do osobní konfigurace
3. AGENTS.md má být krátký, konkrétní a importovat sdílený základ
4. skilly řeší detailní opakované postupy
5. MCP je mocné, takže patří do bezpečnostní debaty
6. tajemství a auto-edit režimy neřešit až po incidentu

---

Další krok

Po školení si každý projděte vlastní prostředí:

• zkontrolovat ~/.codex/config.toml
• nastavit EDITOR
• ověřit dostupné MCP servery
• projít tsm-ai-agents-settings
• doplnit repo-specifické AGENTS.md
• poslat MR do týmových pravidel, pokud něco chybí

Dobrá kontrolní otázka: co by měl agent vědět dřív, než mu dovolím měnit náš kód?