Tryb Q&A - Odpowiadanie na pytania o codebase

Przegląd

Tryb Q&A (Question & Answer) służy do szybkiego uzyskiwania odpowiedzi na pytania dotyczące codebase poprzez:

READ-ONLY eksplorację repozytoriów
Analizę kodu i struktury projektu
Wyszukiwanie wzorców i implementacji
Generowanie zwięzłej, konkretnej odpowiedzi

INPUT:  task.md (pytanie użytkownika)
          ↓
      /qa_answer command
          ↓
     Codex eksploruje:
     - Multiple repositories (READ-ONLY)
     - Code structure
     - Implementation patterns
     - Configuration files
          ↓
OUTPUT: task_answer.md (zwięzła odpowiedź)

Kiedy używać Q&A?

Używaj Q&A gdy:

Potrzebujesz szybkiej odpowiedzi na pytanie o codebase
Chcesz znaleźć konkretną implementację lub wzorzec
Musisz zrozumieć jak działa dany komponent
Szukasz lokalizacji plików lub funkcjonalności
Potrzebujesz dokumentacji istniejącego kodu

NIE używaj Q&A gdy:

Chcesz zmodyfikować kod (używaj PLAN lub TEAM)
Potrzebujesz szczegółowego planu implementacji (używaj PLAN)
Zadanie wymaga zmian w kodzie (używaj TEAM)

Przepływ Q&A mode

1. Inicjalizacja workspace (init_workspace.sh)

bash

bash /workspace/files/helpers/init_workspace.sh

Co robi:

Klonuje repozytoria z konfiguracji task.json
Konfiguruje SSH i git credentials
Przygotowuje środowisko dla AI
Montuje worker files i plugins

Repozytoria: Q&A może pracować z wieloma repozytoriami jednocześnie (przykład DEV-2_10):

sembot-angular (frontend)
sembot-laravel (backend)
sembot-test-automation (testy)

2. Odpowiedź na pytanie (/qa_answer)

bash

/qa_answer /task/task.md

Przepływ Codex:

markdown

1. READ task.md (pytanie użytkownika)

2. ANALIZA pytania:
   - O jaką funkcjonalność pyta użytkownik?
   - Które repozytoria mogą zawierać odpowiedź?
   - Jakie komponenty są związane z pytaniem?

3. EKSPLORUJ codebase (READ-ONLY):
   - Szukaj odpowiednich plików (Glob, Grep)
   - Czytaj konfiguracje (package.json, config files)
   - Analizuj kod (komponenty, serwisy, modele)
   - Identyfikuj wzorce i konwencje

4. GENERUJ odpowiedź:
   - Zwięzła, konkretna odpowiedź
   - Lokalizacje plików z numerami linii
   - Przykłady kodu (jeśli potrzebne)
   - Wyjaśnienie jak to działa

Przykład task.md (INPUT):

markdown

# qa_answer

channel_id: #code-questions
user: Tomek Kowalski (@tkowalski29)
created_at: 2026-01-11 11:00:00
question:

Gdzie w kodzie znajduje się główna implementacja klienta API? Jakie są główne komponenty i w jakich plikach są zdefiniowane?

Przykład task_answer.md (OUTPUT):

markdown

# Odpowiedź Q&A

Główna obsługa klienta HTTP jest w Angularowym `HttpClient`
skonfigurowanym globalnie w `src/app/app.module.ts`
(`provideHttpClient(withInterceptorsFromDi())` + rejestracja
interceptorów pod `HTTP_INTERCEPTORS`).

Najważniejsze komponenty tej konfiguracji:
- `src/app/interceptors/auth-interceptor.service.ts` – dołącza
  nagłówki autoryzacji (Bearer + konto) i tryb plugin.
- `src/app/interceptors/error-interceptor.service.ts` – centralny
  handler błędów HTTP (wylogowanie po 401, przekierowania, komunikaty).
- `src/app/interceptors/timeout-interceptor.service.ts` – domyślny
  timeout 30s z obsługą `408`.

Konfiguracja adresów API:
- Bazowy `apiUrl` w `src/environments/environment*.ts`.
- Lista endpointów w `src/app/configs/api-urls.config.ts`.

3. Ekstrakcja session ID (extract_session_codex.sh)

bash

bash /workspace/files/helpers/extract_session_codex.sh qa_answer /task

Co robi:

Szuka thread_id w logach Docker z subtasku qa_answer
Wyciąga session ID z outputu Codex
Zapisuje do task.json w ai.sessions.codex
Umożliwia kontynuację konwersacji w przyszłości

Format thread_id:

Thread: codex_abc123xyz789

Aktualizacja task.json:

json

"ai": {
  "sessions": {
    "codex": "019bb82d-492c-7960-bb2d-1982a373c3f2",
    "claude": null,
    "gemini": null
  }
}

4. Ekstrakcja odpowiedzi (extract_answer_from_log_codex.sh)

bash

bash /workspace/files/helpers/extract_answer_from_log_codex.sh qa_answer /task

Co robi:

Przeszukuje logi Docker z subtasku qa_answer
Wyodrębnia tekst odpowiedzi wygenerowany przez AI
Czyści formatowanie (usuwa metadane JSON, pozostawia czysty markdown)
Zapisuje do /task/task_answer.md
Kopiuje również do katalogu subtasku dla archiwizacji

Proces ekstrakcji:

Szuka # Odpowiedź Q&A w logu
Wyciąga wszystkie linie do końca odpowiedzi
Usuwa JSON metadata i system messages
Zapisuje czysty markdown

Struktura subtasków

Q&A mode tworzy następujące subtaski w katalogu /task/subtasks/START/:

/task/subtasks/START/
├── done/
│   ├── init_workspace_{uuid}/
│   │   ├── task.json
│   │   └── docker_output.log
│   ├── qa_answer_{uuid}/
│   │   ├── task.json
│   │   ├── task.md (kopia pytania)
│   │   ├── task_answer.md (odpowiedź)
│   │   └── docker_output.log
│   ├── extract_session_{uuid}/
│   │   ├── task.json
│   │   └── docker_output.log
│   └── extract_answer_{uuid}/
│       ├── task.json
│       └── docker_output.log

Konfiguracja task.json

Minimalny przykład Q&A task

json

{
  "task_id": "DEV-2_10",
  "title": "Pytanie",
  "description": "",
  "worker": {
    "type": "qa",
    "docker_path": "qa",
    "docker_finish_stop": true
  },
  "repositories": [
    {
      "folder": "sembot-angular",
      "git_url": "[email protected]:sembot-io/sembot-angular.git",
      "target_branch": "master",
      "working_branch": "claude/DEV-2_10"
    }
  ],
  "ai": {
    "provider": "codex",
    "model": "gpt-5.1-codex-max",
    "mode": "read_only",
    "start_commands": [
      {
        "id": "init_workspace",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/init_workspace.sh",
        "dependencies": []
      },
      {
        "id": "qa_answer",
        "catalog": "START",
        "executor": "codex",
        "command": "/qa_answer /task/task.md",
        "dependencies": ["init_workspace"]
      },
      {
        "id": "extract_session",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/extract_session_codex.sh qa_answer /task",
        "dependencies": ["qa_answer"]
      },
      {
        "id": "extract_answer",
        "catalog": "START",
        "executor": "bash",
        "command": "bash /workspace/files/helpers/extract_answer_from_log_codex.sh qa_answer /task",
        "dependencies": ["qa_answer"]
      }
    ],
    "sessions": {
      "claude": null,
      "codex": null,
      "gemini": null
    }
  },
  "status": "todo"
}

Kluczowe parametry

Parametr	Wartość	Opis
`worker.type`	`"qa"`	Worker dedykowany dla Q&A
`ai.provider`	`"codex"`	Używamy Codex dla Q&A
`ai.model`	`"gpt-5.1-codex-max"`	Model Codex
`ai.mode`	`"read_only"`	Tylko odczyt (bez zmian)
`repositories`	Array	Może być wiele repo

Slash command: /qa_answer

Slash command /qa_answer jest zdefiniowany w pluginie i wykonuje następujące kroki:

Input

Ścieżka do pliku z pytaniem (np. /task/task.md)

Przepływ

Read pytanie - wczytuje task.md
Analiza kontekstu - określa które repo/pliki mogą zawierać odpowiedź
Eksploracja - używa narzędzi (Glob, Grep, Read) do przeszukania kodu
Synteza - generuje zwięzłą odpowiedź z konkretnymi lokalizacjami
Output - zapisuje odpowiedź jako markdown

Narzędzia dostępne dla AI

Glob - wyszukiwanie plików po wzorcu
Grep - szukanie w treści plików
Read - czytanie zawartości plików
Bash - wykonywanie poleceń (np. find, tree)

Format odpowiedzi

Odpowiedź powinna zawierać:

Główną informację - bezpośrednia odpowiedź na pytanie
Lokalizacje - ścieżki plików z numerami linii
Komponenty - lista kluczowych komponentów/klas
Konfiguracja - jeśli dotyczy
Przykłady - fragmenty kodu (opcjonalnie)

Przykłady użycia

Przykład 1: Lokalizacja implementacji

Pytanie:

markdown

Gdzie znajduje się implementacja klienta HTTP API?

Odpowiedź:

markdown

Główna implementacja klienta HTTP:
- `src/app/app.module.ts` - konfiguracja HttpClient
- `src/app/interceptors/auth-interceptor.service.ts` - auth headers
- `src/app/interceptors/error-interceptor.service.ts` - error handling
- `src/app/configs/api-urls.config.ts` - endpoints configuration

Przykład 2: Wzorce i konwencje

Pytanie:

markdown

Jak tworzymy nowe API serwisy w projekcie? Jaki wzorzec używamy?

Odpowiedź:

markdown

Wzorzec tworzenia API serwisów:

1. Lokalizacja: `src/app/dashboard/{feature}/services/`
2. Naming: `{feature}-api.service.ts`
3. Przykład: `src/app/dashboard/users/services/users-api.service.ts`

Wzorzec implementacji:
- Injectable service z providedIn: 'root'
- Inject HttpClient
- Metody zwracają Observable<T>
- Używają prepareUrl() dla endpoint URLs
- Obsługa błędów przez interceptory

Przykład 3: Zależności i integracje

Pytanie:

markdown

Jakie zewnętrzne biblioteki używamy do zarządzania stanem w aplikacji?

Odpowiedź:

markdown

Zarządzanie stanem:

Główna biblioteka: @ngrx/signals (v18.2.x)
- Lokalizacja: `src/app/shared/store/`
- Konfiguracja: `src/app/app.config.ts`

Dodatkowe:
- @ngrx/signals/entities - entity management
- @ngrx/signals/rxjs-interop - integracja z RxJS

Przykłady store:
- `src/app/shared/store/auth.store.ts` - authentication
- `src/app/dashboard/users/store/users.store.ts` - users data

Workflow: Od pytania do odpowiedzi

1. USER tworzy task.md z pytaniem
   ↓
2. ORCHESTRATOR wykrywa task w /todo
   ↓
3. LOAD_TASK przenosi do /in_progress
   ↓
4. INIT_WORKSPACE klonuje repozytoria
   ↓
5. QA_ANSWER eksploruje kod i generuje odpowiedź
   ↓
6. EXTRACT_SESSION zapisuje thread_id do task.json
   ↓
7. EXTRACT_ANSWER zapisuje task_answer.md
   ↓
8. ORCHESTRATOR przenosi task do /done
   ↓
9. USER czyta task_answer.md

Różnice między Q&A a innymi trybami

Aspekt	Q&A	PLAN	TEAM
Cel	Odpowiedź na pytanie	Plan implementacji	Implementacja z kodem
Modyfikuje kod	❌ Nie	❌ Nie	✅ Tak
Output	task_answer.md	task_plan.md	Code changes + commits
AI Provider	Codex	Claude	Claude
Mode	read_only	read_only	write
Repozytoria	Wiele (read-only)	Jedno	Jedno
Git operations	❌ Brak	❌ Brak	✅ Commit, push, PR
Czas wykonania	~1-3 min	~3-10 min	~10-60 min

Worker: qa

Worker qa jest skonfigurowany specjalnie dla zadań Q&A:

Cechy worker qa

Brak modyfikacji kodu - tylko read operations
Multiple repositories - może mieć dostęp do wielu repo jednocześnie
Lightweight - szybsze uruchamianie niż worker do implementacji
Codex optimized - zoptymalizowany dla modelu Codex

Docker configuration

yaml

# docker/qa/docker-compose.yml
services:
  app:
    image: ghcr.io/code-generations/resources_sembot/qa:v1.0.0
    volumes:
      - ${TASK_DIR}:/task:rw
      - workspace:/workspace
    environment:
      - AI_PROVIDER=codex
      - AI_MODE=read_only

Monitorowanie i debugging

Logi wykonania

Wszystkie operacje są logowane w:

/task/subtasks/START/done/qa_answer_{uuid}/docker_output.log

Typowy log zawiera:

Inicjalizacja Claude Code/Codex
Wczytanie pytania z task.md
Serie operacji Read/Grep/Glob
Generowanie odpowiedzi
Zapis task_answer.md

Weryfikacja odpowiedzi

Po zakończeniu sprawdź:

bash

# Główna odpowiedź
cat /task/task_answer.md

# Session ID (dla kontynuacji)
jq '.ai.sessions.codex' /task/task.json

# Pełny log AI
cat /task/subtasks/START/done/qa_answer_*/docker_output.log

Typowe problemy

Problem: Odpowiedź jest niepełna lub niedokładna

Rozwiązanie:

Sprecyzuj pytanie w task.md
Dodaj kontekst (gdzie szukać, jakie komponenty)
Użyj konkretnych terminów technicznych

Problem: Brak task_answer.md po wykonaniu

Rozwiązanie:

Sprawdź logi: extract_answer_{uuid}/docker_output.log
Zweryfikuj czy qa_answer zakończył się poprawnie
Sprawdź format odpowiedzi w qa_answer/docker_output.log

Problem: Codex szuka w niewłaściwych repozytoriach

Rozwiązanie:

Sprecyzuj w pytaniu które repo cię interesuje
Dodaj kontekst techniczny (np. "w aplikacji Angular", "w backend Laravel")

Best Practices

Zadawanie pytań

✅ Dobre pytania:

"Gdzie jest implementacja autoryzacji użytkowników?"
"Jakie interceptory HTTP używamy i co robią?"
"Jak skonfigurowany jest routing w aplikacji Angular?"
"Które serwisy odpowiadają za komunikację z API users?"

❌ Złe pytania:

"Jak działa aplikacja?" (zbyt ogólne)
"Napraw bug w logowaniu" (to nie Q&A, użyj TEAM)
"Dodaj nową funkcję" (to implementacja, użyj TEAM)

Optymalizacja odpowiedzi

Bądź konkretny - pytaj o konkretne komponenty/funkcje
Dodaj kontekst - wskaż technologię, moduł, feature
Ograniczaj zakres - zamiast "wszystko o API" spytaj o konkretny endpoint
Używaj terminologii - techniczne nazwy pomagają w wyszukiwaniu

Multiple repositories

Jeśli pytanie dotyczy wielu repozytoriów, wymień je w task.json:

json

"repositories": [
  {"folder": "frontend", "git_url": "..."},
  {"folder": "backend", "git_url": "..."},
  {"folder": "shared", "git_url": "..."}
]

Codex będzie miał dostęp do wszystkich i może korelować informacje.

Integracja z n8n

Q&A może być zintegrowane z n8n workflow dla automatyzacji:

Webhook trigger

javascript

// n8n workflow: code-question-webhook
{
  "question": "Gdzie jest implementacja...",
  "user": "@tkowalski29",
  "channel": "#code-questions"
}

Task generation

n8n tworzy task.json i task.md automatycznie z webhook data.

Response notification

Po zakończeniu n8n wysyła odpowiedź z task_answer.md na Slack/Discord.

Rozszerzenia i możliwości

Multi-turn conversation

Używając zapisanego session_id można kontynuować konwersację:

json

"ai": {
  "sessions": {
    "codex": "019bb82d-492c-7960-bb2d-1982a373c3f2"
  }
}

Kolejne pytanie w tym samym wątku pozwoli na:

Follow-up questions
Doprecyzowanie odpowiedzi
Dodatkowe szczegóły

Code snippets

Q&A może generować nie tylko lokalizacje, ale też snippety:

markdown

**Przykład użycia:**
\`\`\`typescript
constructor(private http: HttpClient) {}

getUsers(): Observable<User[]> {
  return this.http.get<User[]>(
    prepareUrl('users.list')
  );
}
\`\`\`

Diagram generation

Dla złożonych pytań Q&A może generować diagramy:

markdown

**Przepływ autoryzacji:**
\`\`\`mermaid
graph LR
    A[Login] --> B[AuthService]
    B --> C[HttpClient]
    C --> D[AuthInterceptor]
    D --> E[Backend API]
\`\`\`

Summary

Tryb Q&A to szybki sposób na uzyskanie wiedzy o codebase bez modyfikowania kodu:

✅ READ-ONLY - bezpieczne eksplorowanie
✅ Wielorepozytoryjne - dostęp do multiple codebases
✅ Codex powered - wykorzystuje moc modelu specjalizowanego w kodzie
✅ Szybkie - odpowiedzi w 1-3 minuty
✅ Precyzyjne - konkretne lokalizacje i komponenty
✅ Sesyjne - możliwość kontynuacji konwersacji

Idealne dla:

Onboarding nowych developerów
Szybkie przeszukiwanie legacy code
Dokumentacja istniejącej implementacji
Code review preparation
Architecture understanding

Tryb Q&A - Odpowiadanie na pytania o codebase ​

Przegląd ​

Kiedy używać Q&A? ​

Przepływ Q&A mode ​

1. Inicjalizacja workspace (init_workspace.sh) ​

2. Odpowiedź na pytanie (/qa_answer) ​

3. Ekstrakcja session ID (extract_session_codex.sh) ​

4. Ekstrakcja odpowiedzi (extract_answer_from_log_codex.sh) ​

Struktura subtasków ​

Konfiguracja task.json ​

Minimalny przykład Q&A task ​

Kluczowe parametry ​

Slash command: /qa_answer ​

Input ​

Przepływ ​

Narzędzia dostępne dla AI ​

Format odpowiedzi ​

Przykłady użycia ​

Przykład 1: Lokalizacja implementacji ​

Przykład 2: Wzorce i konwencje ​

Przykład 3: Zależności i integracje ​

Workflow: Od pytania do odpowiedzi ​

Różnice między Q&A a innymi trybami ​

Worker: qa ​

Cechy worker qa ​

Docker configuration ​

Monitorowanie i debugging ​

Logi wykonania ​

Weryfikacja odpowiedzi ​

Typowe problemy ​

Best Practices ​

Zadawanie pytań ​

Optymalizacja odpowiedzi ​

Multiple repositories ​

Integracja z n8n ​

Webhook trigger ​

Task generation ​

Response notification ​

Rozszerzenia i możliwości ​

Multi-turn conversation ​

Code snippets ​

Diagram generation ​

Summary ​

Tryb Q&A - Odpowiadanie na pytania o codebase

Przegląd

Kiedy używać Q&A?

Przepływ Q&A mode

1. Inicjalizacja workspace (init_workspace.sh)

2. Odpowiedź na pytanie (/qa_answer)

3. Ekstrakcja session ID (extract_session_codex.sh)

4. Ekstrakcja odpowiedzi (extract_answer_from_log_codex.sh)

Struktura subtasków

Konfiguracja task.json

Minimalny przykład Q&A task

Kluczowe parametry

Slash command: /qa_answer

Input

Przepływ

Narzędzia dostępne dla AI

Format odpowiedzi

Przykłady użycia

Przykład 1: Lokalizacja implementacji

Przykład 2: Wzorce i konwencje

Przykład 3: Zależności i integracje

Workflow: Od pytania do odpowiedzi

Różnice między Q&A a innymi trybami

Worker: qa

Cechy worker qa

Docker configuration

Monitorowanie i debugging

Logi wykonania

Weryfikacja odpowiedzi

Typowe problemy

Best Practices

Zadawanie pytań

Optymalizacja odpowiedzi

Multiple repositories

Integracja z n8n

Webhook trigger

Task generation

Response notification

Rozszerzenia i możliwości

Multi-turn conversation

Code snippets

Diagram generation

Summary