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

2.7 KiB

Raw Permalink Blame History

Development History

This document records the historical development phases of dance-lessons-coach. Extracted from the original AGENTS.md (Tâche 6 restructure) for lazy-loading compatibility with Mistral Vibe (128k context).

All phases below are completed ✅. They are kept here for traceability and onboarding context — refer to ADRs (adr/) for the technical decisions behind each phase.

Phase 1: Foundation

Go 1.26.1 environment setup
Project structure with cmd/ and pkg/ directories
Core Greet service implementation
CLI interface
Unit tests

Phase 2: Web API

Chi router integration
Versioned API endpoints (/api/v1)
Health endpoint (/api/health)
JSON responses with proper headers

Phase 3: Logging & Architecture

Zerolog integration with Trace level
Context-aware logging
Interface-based design patterns
Dependency injection

Phase 4: Documentation & Testing

Comprehensive AGENTS.md
README.md with usage instructions
Server management guide
API endpoint documentation

Phase 5: Configuration Management

Viper integration for configuration
Environment variable support with DLC_ prefix
Customizable server host/port
Configurable shutdown timeout
Configuration validation and logging
Example configuration file

Phase 6: Graceful Shutdown

Context-aware server initialization
Signal-based termination (SIGINT, SIGTERM)
Configurable shutdown timeout
Readiness endpoint for Kubernetes/service mesh integration
Proper resource cleanup during shutdown
Health endpoint remains healthy during graceful shutdown

Phase 7: OpenTelemetry Integration

OpenTelemetry Go libraries integration
Jaeger compatibility for distributed tracing
Middleware-only approach using otelhttp.NewHandler
Configurable sampling strategies
Graceful shutdown of tracer provider
OTLP exporter with gRPC support

Phase 8: Build System & Documentation

Build script for binary compilation
Binary output to bin/ directory
Comprehensive commit conventions with gitmoji reference
Updated documentation with Jaeger integration guide
Cleaned up configuration files
Enhanced logging configuration with file output support

Removed unnecessary time.Sleep for log flushing
Changed server operational logs from Info to Trace level
Moved all logging setup logic to config package
Simplified server entrypoint to 27 lines
Verified all functionality with comprehensive testing
Updated documentation to reflect final architecture

Beyond Phase 9

Subsequent work (CI/CD, BDD scenarios, ADR audit, JWT, config hot-reloading) is tracked in the Changelog and the corresponding ADRs.

2.7 KiB Raw Permalink Blame History