Gabriel Radureau
88a934dfd2
AGENTS.md passe de 1296 → 130 lignes, sous la cible 200 fixée en D-004 (lazy loading 128k). Ne contient plus que : - Project overview (court) - Tools & technologies (table) - Project structure (tree) - Tableau "Detailed Guides" pointant vers documentation/*.md (12 entrées, tous liens vérifiés valides) - Index des ADR-clés avec liens (13 entrées, tous valides) - AI agent info (court, pointe vers AGENT_USAGE_GUIDE) - Commit conventions (court, pointe vers .vibe/skills/commit-message/) - BDD feature structure (court, pointe vers ADR-0008 + BDD_GUIDE) - Retention policy (gardée intégralement, directive ARCODANGE) - Support (procédure escalade en 5 étapes) Section Version Management (ex-928-1076, ~150 lignes) entièrement SUPPRIMÉE — totalement redondante avec documentation/version-management- guide.md (cf. analyse Phase A `~/.vibe/plans/task-6-phase-a-results.md`). Lien cassé ligne 1277 corrigé : `0019-bdd-feature-structure.md` (inexistant) remplacé par référence à ADR-0008 (bdd-testing) + ADR-0025 (scenario-isolation) qui sont les vraies sources autoritaires. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
131 lines
6.9 KiB
Markdown
131 lines
6.9 KiB
Markdown
# dance-lessons-coach — AI Agent Documentation
|
|
|
|
This file is the directive document auto-loaded by Mistral Vibe (and Claude Code) when working on `dance-lessons-coach`. It stays short by design (≤ 200 lines, lazy-loading compatible with 128k context). Detailed content lives in `documentation/` and is loaded on demand.
|
|
|
|
> **Restructured 2026-05-02** : the original 1296-line `AGENTS.md` was split into focused guides under `documentation/` (Tâche 6 of the ARCODANGE migration Claude → Mistral Vibe). See [`documentation/HISTORY.md`](documentation/HISTORY.md) for context.
|
|
|
|
## 🎯 Project Overview
|
|
|
|
**dance-lessons-coach** is a Go-based web service with CLI capabilities, featuring:
|
|
|
|
- RESTful JSON API with Chi router
|
|
- High-performance Zerolog logging
|
|
- Interface-based architecture
|
|
- Context-aware services
|
|
- Comprehensive testing (unit + BDD with Godog)
|
|
|
|
## 🛠️ Tools & Technologies
|
|
|
|
| Component | Technology | Version |
|
|
|---|---|---|
|
|
| Language | Go | 1.26.1 |
|
|
| Router | Chi | v5.2.5 |
|
|
| Logging | Zerolog | v1.35.0 |
|
|
| Configuration | Viper | v1.21.0 |
|
|
| Testing | Godog (BDD) + std lib | v0.15.1 |
|
|
| Telemetry | OpenTelemetry | v1.43.0 |
|
|
| Tracing | Jaeger compatible | — |
|
|
|
|
## 🗺️ Project Structure
|
|
|
|
```
|
|
dance-lessons-coach/
|
|
├── adr/ # Architecture Decision Records (25+)
|
|
├── cmd/ # Entry points (greet, server)
|
|
├── pkg/ # Core logic (config, greet, server, telemetry, bdd, user, ...)
|
|
├── features/ # BDD scenarios (.feature files)
|
|
├── fixtures/ # BDD test fixtures
|
|
├── scripts/ # Server lifecycle, build, test scripts
|
|
├── documentation/ # Detailed guides (CLI, API, BDD, etc.)
|
|
├── .vibe/skills/ # Project-scoped vibe skills
|
|
├── AGENTS.md # This file (auto-loaded by vibe)
|
|
├── AGENT_CHANGELOG.md # Trace of structural decisions by AI agents
|
|
├── CHANGELOG.md # User-facing changelog
|
|
└── README.md # User documentation
|
|
```
|
|
|
|
## 📚 Detailed Guides (load on demand)
|
|
|
|
The directive content is intentionally short. For details, point Mistral / Claude at the relevant guide:
|
|
|
|
| Topic | Reference |
|
|
|---|---|
|
|
| **CLI commands & server lifecycle** | [`documentation/CLI.md`](documentation/CLI.md) |
|
|
| **REST API endpoints** | [`documentation/API.md`](documentation/API.md) |
|
|
| **OpenTelemetry / Jaeger** | [`documentation/OBSERVABILITY.md`](documentation/OBSERVABILITY.md) |
|
|
| **Troubleshooting** | [`documentation/TROUBLESHOOTING.md`](documentation/TROUBLESHOOTING.md) |
|
|
| **Code patterns & examples** | [`documentation/CODE_EXAMPLES.md`](documentation/CODE_EXAMPLES.md) |
|
|
| **Roadmap & future enhancements** | [`documentation/ROADMAP.md`](documentation/ROADMAP.md) |
|
|
| **Development phases (history)** | [`documentation/HISTORY.md`](documentation/HISTORY.md) |
|
|
| **Agent workflows & best practices** | [`documentation/AGENT_USAGE_GUIDE.md`](documentation/AGENT_USAGE_GUIDE.md) |
|
|
| **BDD testing** | [`documentation/BDD_GUIDE.md`](documentation/BDD_GUIDE.md) |
|
|
| **Version management** | [`documentation/version-management-guide.md`](documentation/version-management-guide.md) |
|
|
| **Local CI/CD testing** | [`documentation/local-ci-cd-testing.md`](documentation/local-ci-cd-testing.md) |
|
|
| **Gitmoji cheatsheet** | [`documentation/GITMOJI_CHEATSHEET.md`](documentation/GITMOJI_CHEATSHEET.md) |
|
|
| **User-facing changelog** | [`CHANGELOG.md`](CHANGELOG.md) |
|
|
| **AI agent decisions log** | [`AGENT_CHANGELOG.md`](AGENT_CHANGELOG.md) |
|
|
|
|
## 📝 Architecture Decision Records (ADRs)
|
|
|
|
The project maintains comprehensive ADRs documenting all major architectural choices. See [`adr/README.md`](adr/README.md) for the index and process.
|
|
|
|
**Key decisions** (load the corresponding ADR for full context):
|
|
|
|
- **Language**: Go 1.26.1 ([ADR-0001](adr/0001-go-1.26.1-standard.md))
|
|
- **Routing**: Chi router ([ADR-0002](adr/0002-chi-router.md))
|
|
- **Logging**: Zerolog ([ADR-0003](adr/0003-zerolog-logging.md))
|
|
- **Design**: Interface-based ([ADR-0004](adr/0004-interface-based-design.md))
|
|
- **Shutdown**: Graceful with readiness ([ADR-0005](adr/0005-graceful-shutdown.md))
|
|
- **Config**: Viper ([ADR-0006](adr/0006-configuration-management.md))
|
|
- **Observability**: OpenTelemetry ([ADR-0007](adr/0007-opentelemetry-integration.md))
|
|
- **Testing**: BDD with Godog ([ADR-0008](adr/0008-bdd-testing.md))
|
|
- **Hybrid testing strategy**: ([ADR-0009](adr/0009-hybrid-testing-approach.md))
|
|
- **CLI**: Cobra subcommands ([ADR-0015](adr/0015-cli-subcommands-cobra.md))
|
|
- **CI/CD**: Trunk-based development ([ADR-0017](adr/0017-trunk-based-development-workflow.md))
|
|
|
|
To add a new ADR: copy an existing one (`adr/0001-*.md`) as a template, edit, then update `adr/README.md`.
|
|
|
|
## 🤖 AI Agent Information
|
|
|
|
**Default agent** (Mistral Vibe CLI):
|
|
|
|
- **Model**: `mistral-medium-3.5` (via alias `mistral-vibe-cli-latest` — devstral-2 lineage)
|
|
- **Role**: Development assistant
|
|
- **Capabilities**: code generation, refactoring, test creation, documentation, architecture guidance, best-practices enforcement
|
|
|
|
For agent-specific workflows (programmer agent, product owner agent, BDD test generation), see [`documentation/AGENT_USAGE_GUIDE.md`](documentation/AGENT_USAGE_GUIDE.md).
|
|
|
|
For migration context (Claude Code → Mistral Vibe in progress), see `~/.vibe/plans/migration-claude-vers-mistral-phase-1.md`.
|
|
|
|
## 📝 Commit Conventions
|
|
|
|
Conventional Commits + gitmoji. Full reference and tooling in the project skill:
|
|
|
|
- **Skill**: [`.vibe/skills/commit-message/`](.vibe/skills/commit-message/) (auto-loaded by vibe in this project)
|
|
- **Cheatsheet**: [`documentation/GITMOJI_CHEATSHEET.md`](documentation/GITMOJI_CHEATSHEET.md)
|
|
|
|
Quick rule: every commit starts with a gitmoji + conventional type (e.g., `✨ feat: add user authentication`, `🐛 fix: prevent race condition`, `📝 docs: update API guide`).
|
|
|
|
## 📋 BDD Feature Structure
|
|
|
|
All user stories and BDD features follow the conventions in [ADR-0008 — BDD Testing](adr/0008-bdd-testing.md) and the practical guide [`documentation/BDD_GUIDE.md`](documentation/BDD_GUIDE.md). Scenario isolation pattern is detailed in [ADR-0025](adr/0025-bdd-scenario-isolation-strategies.md).
|
|
|
|
## 🗑️ Retention Policy
|
|
|
|
| Domain | Policy |
|
|
|---|---|
|
|
| **ADRs** | Review quarterly. Deprecate via `Status: Deprecated`. Remove after 6 months of deprecation. |
|
|
| **Documentation** | Archive completed projects to `archive/`. Remove after 12 months. |
|
|
| **Scripts** | Move unused to `scripts/deprecated/`. Remove after 6 months. |
|
|
| **Skills** | Move unused to `.vibe/skills/deprecated/`. Remove after 6 months. |
|
|
|
|
## 📞 Support
|
|
|
|
For issues or questions:
|
|
|
|
1. Check the relevant guide above (table "Detailed Guides")
|
|
2. Review the corresponding ADR
|
|
3. Examine existing implementations in `pkg/`
|
|
4. Consult the agent's reasoning trace (sessions in `~/.vibe/logs/session/`) for context-rich help
|
|
5. As last resort, consult Go / Chi / Zerolog / Viper upstream documentation
|