Files

Gabriel Radureau 41ee8c56ac 📝 docs(restructure): split AGENTS.md into focused guides (Tâche 6 Phase B)

Création de 9 fichiers neufs pour décharger AGENTS.md (1296 lignes →
~130) en documents lazy-loadables, compatibles avec la limite de
contexte 128k de Mistral Vibe (cf. ARCODANGE migration Phase 1,
Tâche 6 du curriculum).

Sept guides ciblés sous documentation/ :
- HISTORY.md            : phases historiques 1-9 du développement
- CLI.md                : commandes CLI, server lifecycle, config DLC_*
- API.md                : endpoints REST, OpenAPI, Greet v1/v2
- OBSERVABILITY.md      : OpenTelemetry + Jaeger, sampler types, test
- TROUBLESHOOTING.md    : issues connues + pointeurs vers guides spé
- CODE_EXAMPLES.md      : snippets endpoint/logging/context, pointeurs ADR
- ROADMAP.md            : potential features, architectural improvements

Deux fichiers racine :
- CHANGELOG.md          : user-facing, format Keep a Changelog
- AGENT_CHANGELOG.md    : décisions structurantes des agents AI
                          (référencé par AGENTS.md, n'existait pas)

Le contenu est extrait fidèlement d'AGENTS.md sans réinterprétation.
Phase C (réécriture AGENTS.md court) suit dans le commit suivant.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-02 23:28:10 +02:00

3.0 KiB

Raw Permalink Blame History

Troubleshooting

Common issues and their resolution. Extracted from the original AGENTS.md and merged with relevant sections from AGENT_USAGE_GUIDE.md and BDD_GUIDE.md. Refer back to those guides for context-specific troubleshooting (agent workflows, BDD test failures).

Port Already in Use

# Find and kill process using port 8080
kill -TERM $(lsof -ti :8080)

# Force kill if graceful does not work
kill -9 $(lsof -ti :8080)

Server Not Responding

# Check if running
curl -s http://localhost:8080/api/health

# Restart server using control script
./scripts/start-server.sh restart

# View recent logs
./scripts/start-server.sh logs

If health endpoint returns connection refused, the server may have crashed. Check logs in ./scripts/start-server.sh logs for stack traces.

Dependency Issues

# Clean and rebuild
go mod tidy
go build ./...

# If dependency version conflicts persist
go mod download
go mod verify

Tests Failing

Unit tests

# Run with verbose output
go test -v ./...

# Check specific test
go test ./pkg/greet/ -run TestName

BDD tests

See BDD_GUIDE.md for the full BDD troubleshooting workflow (Godog setup, scenario isolation, step matching). Common BDD issues:

Step not found → check pkg/bdd/steps/ for the step definition file
Scenario state leaking → review ADR-0025 for the isolation pattern
Database not reset → ensure the test fixtures cleanup runs (BDD scenario After hooks)

Configuration Not Loading

The application logs the configuration source at startup. Check logs for:

[INF] Configuration loaded from: file:config.yaml
# or
[INF] Configuration loaded from: env
# or
[INF] Configuration loaded from: defaults

If config is not loading as expected:

Verify file exists and is readable: ls -la config.yaml
Verify env vars are exported: env | grep DLC_
Check for typos in keys (case-sensitive)
Review AGENT_USAGE_GUIDE.md section "Configuration troubleshooting"

OpenTelemetry Not Tracing

Verify Jaeger is running: docker ps | grep jaeger
Check DLC_TELEMETRY_ENABLED=true in environment or telemetry.enabled: true in config
Verify OTLP endpoint reachable: nc -zv localhost 4317
Check sampler is not always_off
See OBSERVABILITY.md for full setup

Build Failures

# Clear caches
go clean -cache -modcache
go mod download

# Rebuild
go build ./...

If errors persist, see local-ci-cd-testing.md for the CI/CD pipeline that mirrors the production build.

Where to Look Next

Agent-specific issues (vibe, mistral, programmer agent) → AGENT_USAGE_GUIDE.md
BDD-specific issues → BDD_GUIDE.md
Version/release issues → version-management-guide.md
CI/CD issues → local-ci-cd-testing.md

3.0 KiB Raw Permalink Blame History