2026-04-08: Setting up the Codex developer handbook in the Groupe-3D repository
Context
Section titled “Context”Following the documentation distribution decision (2026-04-08-documentation-distribution), several types of cross-cutting information need to be centralised in a team handbook:
- Available AI tools and recommended resources
- Development workflows (from Linear ticket to PR)
- Branch and PR naming conventions
- Platform usage guide (Scalingo, Vercel, Scaleway)
In addition to these topics from the documentation mapping, the following needs were identified independently:
- How to find a project’s documentation
- List of team rituals
- List of tools used and available
These topics do not belong in any specific project’s README. We need a centralised, versioned space accessible to the whole team.
Decision
Section titled “Decision”We create a codex folder at the root of the Groupe-3D/Groupe-3D repository.
This folder is the developer toolbox for the organization. It will host the following sections (non-exhaustive list, to be expanded over time via dedicated PRs):
- How to find a project’s documentation
- List of team rituals
- List of tools used and available
- Available AI tools and recommended resources
- Development workflows (from Linear ticket to PR)
- Branch and PR naming conventions
- Platform usage guide: Scalingo, Vercel, Scaleway
A codex/README.md file serves as the table of contents and entry point for the codex.
Rationale
Section titled “Rationale”Why host it in Groupe-3D/Groupe-3D
Section titled “Why host it in Groupe-3D/Groupe-3D”This repository is already the organizational reference: it holds cross-cutting ADRs, the shared Renovate configuration, and technical guides. It is natural to also centralise team practices there, keeping everything that applies organization-wide in one place.
Why a dedicated folder rather than the existing guides/ folder
Section titled “Why a dedicated folder rather than the existing guides/ folder”The guides/ folder contains operational technical guides for specific tools (e.g. Renovate). The codex is different in nature: it is a toolbox focused on team practices and development culture. Mixing the two would harm the clarity and maintainability of both.
Why version it in Git rather than a dedicated tool (Notion, Confluence…)
Section titled “Why version it in Git rather than a dedicated tool (Notion, Confluence…)”Versioning the codex in Git allows tracking the history of changes, proposing modifications via PR with review, and using the same tools as the rest of the organization’s work. It also promotes adoption by developers, for whom this repository is already familiar.
Trade-offs
Section titled “Trade-offs”- Contributing to the codex requires a PR, which is more rigorous than editing a Notion page. This may be a barrier to quick, informal additions.
- The codex has no dedicated search interface. Navigation relies on links between files and the folder structure, which requires keeping the table of contents up to date.
Consequences
Section titled “Consequences”- A
codex/folder is created at the root of the Groupe-3D/Groupe-3D repository. - A
codex/README.mdfile is created and maintained as the codex’s table of contents. - The sections listed in this decision are written progressively via dedicated PRs, assigned to the relevant contributors.
- Any cross-cutting organizational practice that does not belong in a specific project must be documented in
codexrather than in a project README.