Współpraca zespołowa i współdzielona konfiguracja

Twój zespół ośmiu programistów ma każdy własną konfigurację Codex. Jeden używa approval_policy = "never" z pełnym dostępem. Drugi ma ścisły tryb read-only. Trzeci ma skonfigurowanych pięć serwerów MCP, których nikt inny nie używa. Gdy dzielą się promptami lub przepływami pracy, dostają zupełnie różne wyniki. Konfiguracja zespołowa rozwiązuje to, ustanawiając współdzieloną linię bazową przy zachowaniu indywidualnej elastyczności.

Czego się nauczysz

• Strategia wdrożenia Team Config z użyciem współdzielonych config.toml, reguł i umiejętności
• Konwencje AGENTS.md, które działają dla zespołów od 5 do 50 programistów
• Wzorce współpracy przy udostępnianiu promptów, umiejętności i przepływów pracy przeglądu
• Szablony onboardingowe, które pozwalają nowym członkom zespołu być produktywnymi z Codex w jeden dzień

Współdzielona i projektowa konfiguracja

Codex czyta konfigurację z wielu warstw. Najprostszy sposób na ustandaryzowanie pojedynczego repozytorium to zacommitowanie konfiguracji, reguł i umiejętności o zasięgu projektu obok twojego kodu:

Typ	Ścieżka	Przeznaczenie
Config	.codex/config.toml	Tryb sandboxa, model, polityka zatwierdzania, serwery MCP
Reguły	.codex/rules/	Które polecenia Codex może uruchamiać poza sandboxem
Umiejętności	.agents/skills/	Współdzielone umiejętności dostępne dla wszystkich członków zespołu

Notatka

Te zacommitowane do repozytorium ścieżki obejmują jeden projekt. Do standaryzacji w obrębie całej organizacji Codex udostępnia też dedykowaną funkcję Team Config, która współdzieli config.toml, rules/ i skills/ centralnie, bez powielania ich w każdym repozytorium. Poniższe pliki o zasięgu projektu to lekki odpowiednik na poziomie pojedynczego repozytorium.

Konfiguracja na poziomie projektu

Zacommituj .codex/config.toml do swojego repozytorium:

# .codex/config.toml -- Shared team defaults
model = "gpt-5.5"
approval_policy = "on-failure"
sandbox_mode = "workspace-write"

# Shared MCP servers
[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"

# Disable web search for security-sensitive projects
web_search = "disabled"

Zacommitowany do projektu .codex/config.toml faktycznie stoi wyżej niż osobisty ~/.codex/config.toml każdego programisty, więc ustanawia linię bazową zespołu, którą wszyscy dziedziczą. Poszczególne osoby mogą nadal nadpisać konkretne wartości wyżej w łańcuchu za pomocą flag CLI (-c key=value) lub --profile. Jeden wyjątek: jeśli programista oznaczy projekt jako niezaufany, Codex całkowicie pomija warstwy .codex/ o zasięgu projektu i wraca do osobistych, systemowych i wbudowanych wartości domyślnych.

Prompt: Wygeneruj konfigurację zespołową

“Analyze this repository’s structure and create a .codex/config.toml that: sets workspace-write sandbox mode, configures the Linear MCP server, enables shell_snapshot for faster commands, and sets the review model to gpt-5.5. Also create a rules file that allows npm, pnpm, git, and make commands but prompts for anything else.”

Gdy wkleisz wygenerowany plik, zweryfikuj dwa klucze: shell_snapshot należy do tabeli [features] ([features], a potem shell_snapshot = true), a nie jest kluczem najwyższego poziomu, a nadpisanie /review to klucz najwyższego poziomu review_model.

Współdzielone konwencje AGENTS.md

Dla zespołów ustrukturyzuj swoją hierarchię AGENTS.md:

AGENTS.md                           # Konwencje obowiązujące w całym repozytorium
  |-- packages/api/AGENTS.md        # Konwencje zespołu API
  |-- packages/web/AGENTS.md        # Konwencje zespołu frontendowego
  |-- services/payments/AGENTS.md   # Konwencje zespołu płatności

Co umieścić w głównym AGENTS.md

# Team Conventions

## Code Style
- Use TypeScript strict mode for all new files
- Follow the error handling patterns in src/lib/errors.ts
- All API routes must have OpenAPI annotations

## Workflow
- Run pnpm lint && pnpm test before committing
- New endpoints need integration tests in tests/integration/
- Database changes need a migration file in migrations/

## Review
- Security-sensitive changes require two human reviewers
- Performance changes need benchmark results in the PR description

Co umieścić w AGENTS.md na poziomie pakietu

packages/api/AGENTS.md

## API-Specific Rules
- Use the centralized error handler, never throw raw errors
- Rate limiting must be added to all public endpoints
- Authentication middleware is in src/middleware/auth.ts
- Test utilities are in tests/utils/api-helpers.ts

Współdzielone umiejętności

Twórz ogólnozespołowe umiejętności w .agents/skills/ w katalogu głównym repozytorium:

---
name: pr-ready
description: Prepare the current changes for a pull request by running
  all checks, fixing issues, and generating a PR description.
---

# PR Readiness Check

1. Run pnpm lint and fix any issues
2. Run pnpm test and fix any failures
3. Run pnpm type-check and fix any errors
4. Generate a PR description with:
   - Summary of changes
   - Testing approach
   - Breaking changes (if any)
5. Report the results

Członkowie zespołu wywołują ją za pomocą $pr-ready na dowolnej powierzchni Codex.

Onboarding nowych członków zespołu

Utwórz listę kontrolną onboardingową:

1. Zainstaluj aplikację Codex i CLI
2. Uruchom codex login, aby uwierzytelnić się w przestrzeni roboczej ChatGPT swojego zespołu
3. Sklonuj repozytorium (które zawiera .codex/config.toml i AGENTS.md)
4. Zainstaluj zalecane serwery MCP: codex mcp add linear --url https://mcp.linear.app/mcp
5. Uruchom zadanie testowe: codex "Summarize the current instructions and list available skills"
6. Przejrzyj bibliotekę promptów zespołu dla typowych przepływów pracy

Prompt: Weryfikacja onboardingu

“Verify my Codex setup: check that AGENTS.md is loaded correctly, list all configured MCP servers, verify the sandbox mode is workspace-write, and run pnpm test to confirm the development environment works. Report any issues.”

Wzorce współpracy

Biblioteki promptów

Utrzymuj kolekcję sprawdzonych promptów w swoim repozytorium:

.github/codex/prompts/
  review.md          # PR review prompt
  fix-ci.md          # CI failure auto-fix
  migration.md       # Database migration template
  security-scan.md   # Security audit prompt

Odwoływuj się do nich w GitHub Actions lub udostępniaj w dokumentacji zespołowej.

Udostępnianie umiejętności

Umiejętności zacommitowane w .agents/skills/ są dostępne dla wszystkich w zespole. Dla osobistych umiejętności użyj ~/.agents/skills/. Dla umiejętności obowiązujących w całej organizacji, wdróż do /etc/codex/skills/ za pomocą zarządzania konfiguracją.

Kiedy to nie działa

• Konfiguracja zespołowa koliduje z osobistą: Zacommitowany do projektu .codex/config.toml ma pierwszeństwo przed osobistym ~/.codex/config.toml (flagi CLI i wartości --profile nadal stoją wyżej niż oba). Domyślne wartości zespołu zwykle więc wygrywają — chyba że programista oznaczył projekt jako niezaufany, w którym to przypadku Codex całkowicie pomija warstwy projektu .codex/ i wraca do osobistych, systemowych i wbudowanych wartości domyślnych. Jeśli indywidualne wyniki nadal się rozjeżdżają, sprawdź, czy nie ma błąkających się nadpisań CLI lub odrzuconego pytania o zaufanie.
• AGENTS.md za duży: Łączny rozmiar wszystkich plików AGENTS.md jest domyślnie ograniczony do 32KB. Podziel wytyczne na zagnieżdżone pliki i w razie potrzeby zwiększ project_doc_max_bytes.
• Nowy członek zespołu dostaje inne wyniki: Sprawdź, czy ma skonfigurowane te same serwery MCP i czy jego osobista konfiguracja nie nadpisuje krytycznych ustawień zespołowych.
• Umiejętności nie pojawiają się: Umiejętności muszą znajdować się w katalogach .agents/skills/. Codex skanuje od bieżącego katalogu w górę do katalogu głównego repozytorium. Zrestartuj Codex, jeśli nowo dodana umiejętność się nie pojawia.

Co dalej

• Inżynieria promptów — Pisz prompty, które działają w całym zespole
• Strategie przeglądu — Standaryzuj praktyki przeglądu
• Zarządzanie korporacyjne — Skaluj konfigurację zespołową do poziomu organizacji