Deze documentatie wordt actief uitgebreid — kom regelmatig terug.

ADR-00005: Use AGENTS.md for shared AI guidelines

Approval Status

Status flow: Proposed → Accepted → Reviewed → Approved (or Rejected), or Not Required. A superseded ADR keeps its file; only its status changes to Superseded by NNNNN.

Governance body	Status	Last update
CTN Project Team	Approved	2026-05-29
CTN Technical Advisory Board	Not Required	2026-07-08
CTN Steering Committee	Not Required	2026-07-08
BDI Conformance Team	Not Required	2026-07-08
BDI Framework Team	Not Required	2026-07-08

Context and Problem Statement

As the project increasingly uses multiple AI-assisted development tools (e.g., an AI agent, Claude Code, Cursor), there is a risk of fragmented instructions and inconsistent coding patterns. We previously chose CLAUDE.md as a shared file, but AGENTS.md has emerged as a more tool-agnostic, industry-supported standard stewarded by the Agentic AI Foundation.

Considered Options

Option 1: Continue using CLAUDE.md as primary

Description: Keep CLAUDE.md as the source of truth.
Pros: Already implemented.
Cons: Naming is biased towards one tool (Claude); may not be automatically recognized by other agents.

Option 2: Adopt AGENTS.md as the primary shared file

Description: Use AGENTS.md (a growing open standard) as the central repository of AI instructions and project context. Other tool-specific files (like CLAUDE.md) reference this file.
Pros: Tool-agnostic; follows emerging industry standards; supported by multiple AI vendors (OpenAI, Anthropic, Google, Cursor); readable by humans and all AI agents.
Cons: Requires minor migration from existing setup.

Decision Outcome

Chosen option: Option 2: Adopt AGENTS.md as the primary shared file.

Rationale

Standardization: AGENTS.md is an open format stewarded by the Agentic AI Foundation, making it the most future-proof choice for cross-tool compatibility.
Clarity: It clearly separates human-centric documentation (README.md) from agent-centric instructions (AGENTS.md).
Scalability: Supports hierarchical nesting for large repositories and monorepos.

Consequences

Positive: Single, tool-agnostic source of truth for AI context; easier onboarding for any new AI tools; consistent application of project standards.
Negative: Tool-specific config files (e.g. agent-specific guideline files or CLAUDE.md) still exist but act as pointers to AGENTS.md to ensure compatibility with tools that have fixed defaults.

Implementation Plan

Phase 1: Create AGENTS.md at the project root with core project context, tech stack, and AI best practices.
Phase 2: Update CLAUDE.md to point to AGENTS.md.
Phase 3: Update an AI agent guidelines to reference AGENTS.md.