From 6bf7e258b5c9f9792ab5d28a52139acdea947fdd Mon Sep 17 00:00:00 2001 From: Olivier Cots Date: Thu, 30 Jul 2026 15:47:29 +0200 Subject: [PATCH] docs(agents): fix import convention and add missing Handbook tenets CLAUDE.md/AGENTS.md said `import Pkg: Pkg`, never bare `using`. The Handbook (philosophy/modules.md) mandates the opposite: `import` is never used anywhere in the ecosystem, only `using`, always qualified (`using Pkg: Pkg`, never bare `using Pkg`). Also add three Handbook tenets missing from Key Conventions: structured errors, enforced type stability, and "1-D is a scalar". Co-Authored-By: Claude Sonnet 5 --- AGENTS.md | 5 ++++- CLAUDE.md | 5 ++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 9fd48c8b..1a816259 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,8 +35,11 @@ Design philosophy, operational rules, plan templates, and CI/CD conventions live ## Key Conventions - **No top-level exports** — use `Package.Submodule.symbol` everywhere. -- **Qualified imports** — `import Pkg: Pkg`, never bare `using`. +- **Qualified imports** — `using Pkg: Pkg`, never bare `using Pkg`; `import` is never used. - **Fake types at module top-level** — never inside test functions. +- **Structured errors** — seven typed exceptions under `CTException`; pick by the IncorrectArgument / PreconditionError / NotImplemented rule. +- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET; setup-path dispatch is fine. +- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a length-1 vector. - **Plans before code** — write a plan and confirm with the user before touching files. - **Docstrings last** — written only after all implementation steps are stable. - **Never commit or push without explicit user approval.** diff --git a/CLAUDE.md b/CLAUDE.md index a9007d83..f8b1e355 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -35,8 +35,11 @@ Design philosophy, operational rules, plan templates, and CI/CD conventions live ## Key Conventions - **No top-level exports** — use `Package.Submodule.symbol` everywhere. -- **Qualified imports** — `import Pkg: Pkg`, never bare `using`. +- **Qualified imports** — `using Pkg: Pkg`, never bare `using Pkg`; `import` is never used. - **Fake types at module top-level** — never inside test functions. +- **Structured errors** — seven typed exceptions under `CTException`; pick by the IncorrectArgument / PreconditionError / NotImplemented rule. +- **Type stability enforced** — hot paths must be `@inferred`-clean, verified with JET; setup-path dispatch is fine. +- **1-D is a scalar** — a one-dimensional state/control/variable is a `Number`, never a length-1 vector. - **Plans before code** — write a plan and confirm with the user before touching files. - **Docstrings last** — written only after all implementation steps are stable. - **Never commit or push without explicit user approval.**