Efektywne promptowanie i strategie AGENTS.md

Dwóch programistów z tego samego zespołu daje Codex to samo zadanie. Jeden dostaje czystą, dobrze przetestowaną implementację w dwóch turach. Drugi dostaje rozwlekły, na wpół zepsuty wynik wymagający trzech poprawek. Różnica to nie szczęście ani losowość modelu — to jakość promptu. Codex jest tylko tak efektywny, jak instrukcje, które mu dajesz, a te instrukcje pochodzą z dwóch źródeł: twoich promptów i plików AGENTS.md.

Czego się nauczysz

• Struktura promptu, która konsekwentnie daje wysokiej jakości wyniki Codex za pierwszym razem
• Wzorce AGENTS.md zapewniające właściwy kontekst bez marnowania tokenów na nieistotne wytyczne
• Techniki promptowania opartego na weryfikacji, które sprawiają, że Codex sam sprawdza swoją pracę
• Antywzorce, których należy unikać, a które marnują tokeny i dają gorsze wyniki

Anatomia efektywnego promptu

Każdy wysokiej jakości prompt Codex ma cztery komponenty:

1. Co — Konkretne zadanie, jasno sformułowane
2. Gdzie — Pliki, katalogi lub moduły, których dotyczy
3. Jak — Wzorce, konwencje lub ograniczenia do przestrzegania
4. Zweryfikuj — Jak Codex powinien zwalidować swoją pracę

Implement rate limiting for the /api/v2/orders endpoint.        [Co]
The route is in src/routes/orders.ts and the middleware          [Gdzie]
directory is src/middleware/.
Follow the pattern used in src/middleware/auth-limiter.ts.       [Jak]
Add a unit test in tests/middleware/. Run npm test to verify.    [Zweryfikuj]

Prompt: Zadanie oparte na weryfikacji

“Add input validation to the user registration endpoint in src/routes/auth.ts. Use Zod schemas matching the patterns in src/schemas/. Validate email format, password strength (min 8 chars, one number, one special char), and username uniqueness. Write tests in tests/routes/auth.test.ts. Run npm test after each change to verify nothing breaks.”

Hierarchia AGENTS.md

Codex czyta pliki AGENTS.md w określonej kolejności i konkatenuje je. Pliki bliżej twojego katalogu roboczego nadpisują wcześniejsze wytyczne.

Globalny AGENTS.md

Utwórz ~/.codex/AGENTS.md dla uniwersalnych preferencji:

# Working Agreements

- Always run tests after modifying code files
- Prefer pnpm for dependency management
- Ask before adding new production dependencies
- Use TypeScript strict mode for all new files

AGENTS.md w katalogu głównym repozytorium

Konwencje obowiązujące w całym projekcie:

# Repository Expectations

- Run pnpm lint before opening a pull request
- Follow the error handling pattern in src/lib/errors.ts
- All API routes must have OpenAPI annotations
- Test files live next to source files: foo.ts -> foo.test.ts

Zagnieżdżone AGENTS.md dla specjalizacji

Dla monorepo dodaj wytyczne specyficzne dla katalogów:

services/payments/AGENTS.md

- Use make test-payments instead of npm test
- Never modify payment amounts without explicit user confirmation
- All database queries must use the payments-specific connection pool
- Follow PCI-DSS logging rules: never log card numbers or CVVs

Prompt: Wygeneruj AGENTS.md dla swojego projektu

“Analyze this repository’s structure, test patterns, linting configuration, and coding conventions. Generate an AGENTS.md file that captures the key instructions a new Codex session should follow. Include: test commands, lint commands, naming conventions, file organization patterns, and any project-specific rules you can infer from the codebase.”

Antywzorce promptowania

Zlewozmywak

Źle: “Refactor the entire auth system, add tests, update docs, fix all lint issues, and optimize performance.”

Ten prompt próbuje zrobić pięć rzeczy naraz. Agent prawdopodobnie zrobi mierną robotę ze wszystkimi.

Dobrze: Rozdziel na pięć skupionych promptów, każdy we własnym wątku.

Przeładowanie placeholderami

Źle: “Add [TYPE] validation to [ENDPOINT] using [LIBRARY] following [PATTERN].”

Dobrze: Bądź konkretny. “Add Zod validation to the POST /users endpoint following the pattern in src/schemas/order.schema.ts.”

Niejawne oczekiwanie

Źle: “Fix the bug.”

Dobrze: “The login endpoint returns 500 when the email contains a plus sign. The error is in src/routes/auth.ts around the email parsing logic. Add a regression test that covers email addresses with plus signs.”

Nadmiernie rozbudowany kontekst

Źle: AGENTS.md o 2000 liniach opisujący każdy aspekt całej organizacji.

Dobrze: 100-liniowy główny AGENTS.md z zagnieżdżonymi 50-liniowymi plikami dla każdego serwisu. Łączny kontekst na zadanie: 150 linii.

Zaawansowane techniki promptowania

Promptowanie z planem na początku

Poproś Codex o zaproponowanie planu przed implementacją:

Before making any changes, outline a plan for migrating our Express
middleware to Fastify hooks. List each file that needs changes and
the specific transformation for each. Wait for my approval before
implementing.

Zakotwiczenie ograniczeń

Jawnie określ, czego agent NIE powinien robić:

Update the user model to support soft deletes. Do NOT modify the
migration files -- I will handle migrations separately. Do NOT
change the API response format. Only modify the model, repository,
and service layers.

Pętle samoweryfikacji

Poproś Codex o weryfikację własnej pracy:

After implementing the changes:
1. Run pnpm test and fix any failures
2. Run pnpm lint and fix any warnings
3. Verify the API still returns the correct response shape by
   checking against the OpenAPI spec
4. Report what you changed and the verification results

Kiedy to nie działa

• Agent ignoruje wytyczne AGENTS.md: Sprawdź, czy Codex załadował plik, pytając “Summarize the current instructions.” Jeśli plik jest za duży, może zostać obcięty (domyślny limit: 32KB). Podziel na zagnieżdżone pliki.
• Prompt daje niespójne wyniki: Dodaj więcej ograniczeń. Niejasne prompty dają zmienne wyniki. Konkretne prompty z krokami weryfikacji dają spójne wyniki.
• Okno kontekstu się zapełnia: Długie pliki AGENTS.md i wiele serwerów MCP zjadają kontekst. Przytnij AGENTS.md do niezbędnych rzeczy i wyłącz nieużywane serwery MCP.
• Agent nadmiernie refaktoryzuje: Dodaj jawne ograniczenia, takie jak “Do NOT refactor unrelated code” lub “Only modify the files listed above.”

Co dalej

• Wzorce kontekstu — Efektywnie zarządzaj kontekstem w długich sesjach
• Strategie przeglądu — Efektywnie przeglądaj wyniki agenta
• Triki efektywności — Szybkie wskazówki, które uczynią każdy prompt bardziej efektywnym