From 5c25b4fe5af606fdeab819b21bd4580b0b776412 Mon Sep 17 00:00:00 2001 From: Julian Lechner Date: Thu, 24 Sep 2026 21:44:29 +0200 Subject: [PATCH] docs(rules): document focused rule directories --- AI-Instructions.md | 3 +-- docs/configuration.md | 2 +- docs/extending-configuration.md | 2 +- docs/skills.md | 2 +- 4 files changed, 4 insertions(+), 5 deletions(-) diff --git a/AI-Instructions.md b/AI-Instructions.md index 791a96a..9a3826c 100644 --- a/AI-Instructions.md +++ b/AI-Instructions.md @@ -15,7 +15,7 @@ Keep the architecture as: - Do not duplicate shared behavior in adapters. - Treat `generated/` as reproducible build output. - Maintain equivalent support for both Codex and Claude Code. -- Keep technology-specific rules in separate files under `shared/rules/`. +- Keep each language, framework, and library in its own directory under `shared/rules/`, with an index and focused Markdown rules. Keep security in `shared/rules/security/` and cross-cutting rules such as Git and Microsoft directly under `shared/rules/`. - Generate those rule files beside `AGENTS.md` and `CLAUDE.md`; load them only when their subject applies. ## Portability @@ -60,4 +60,3 @@ Write all repository content, generated instructions, scripts, prompts, document - Never commit changes unless explicitly instructed. - Preserve unrelated user changes. - diff --git a/docs/configuration.md b/docs/configuration.md index 5d60b27..88c6ea7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -2,7 +2,7 @@ Codex receives a generated global `AGENTS.md`, agent TOML files, skills, rule files, and a `config.toml` adapter. It keeps workspace sandboxing, automatic approval review, `agents.enabled = true`, `agents.max_concurrent_threads_per_session = 5`, and `agents.max_depth = 1`. Claude Code receives a generated global `CLAUDE.md`, agent Markdown files, skills, and `settings.json` with `auto` permissions, explicit `Agent` permission, and five-operation concurrency. Installation resolves user paths at runtime; the repository contains no machine-specific paths. -Both clients embed `shared/rules/general.md` and the rule-loading conditions from `shared/global-instructions.md`. Codex loads applicable focused rules from `rules/`; Claude generates a matching skill for each focused rule file or rule directory. Angular, WPF, and UI/UX rules have small entry points with references loaded by topic. `security.md` is the baseline for programming tasks; focused security rules cover authentication, web, API, data, files, network, cryptography, and supply-chain work. +Both clients embed `shared/rules/general.md` and the rule-loading conditions from `shared/global-instructions.md`. Rules for languages and frameworks live in their own directories, with an `index.md` entry point and focused Markdown rules under `references/`. Security has its own directory with a baseline entry point and focused rules for authentication, web, APIs, data, files, network, cryptography, and supply chains. Git, Microsoft, and cross-cutting rules remain directly under `shared/rules/`. Codex receives the full directory tree; Claude generates a skill for each rule and copies supporting references alongside the index skill. The Codex adapter sets `agents.max_depth = 1` and does not enable `features.multi_agent_v2`. Shared instructions also prohibit subagents from creating further subagents. Agent roles are optional, not stages that every task must run. diff --git a/docs/extending-configuration.md b/docs/extending-configuration.md index ab35673..d0ad3ec 100644 --- a/docs/extending-configuration.md +++ b/docs/extending-configuration.md @@ -4,7 +4,7 @@ Shared definitions are the source of truth. Rebuild after every semantic change. ## Add a rule -Create a focused Markdown file in `shared/rules/` and add its loading condition to `shared/global-instructions.md`. Claude rule skills are generated from the rule filenames; Codex loads the referenced rule files directly. Put always-applicable guidance in `general.md`, which the build embeds for both clients; a new rule file is not automatically embedded. +Create cross-cutting rules such as Git or Microsoft guidance as focused Markdown files directly in `shared/rules/`. Put each language, framework, or library in its own directory with an `index.md` and focused files under `references/`; put security rules in `shared/rules/security/`. Add the matching loading condition and generated Claude skill name to `shared/global-instructions.md` and the directory index. The build copies rule trees to Codex and generates Claude skills from each rule file. Put always-applicable guidance in `general.md`, which the build embeds for both clients; a new rule file is not automatically embedded. ## Add a skill diff --git a/docs/skills.md b/docs/skills.md index 0d06de8..2245919 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -18,7 +18,7 @@ Claude's generated package additionally has `skills/rules/`: one skill per focus `shared/rules/`. The rule-to-skill loading conditions live in `shared/global-instructions.md`, so full rule text loads only when Claude invokes a matching skill instead of sitting permanently in context. Codex reads the matching rule files directly. Both clients embed the general rules in their global instructions. -Split Angular, WPF, and UI/UX rules load supporting references only for the topic being worked on. See [Configuration](configuration.md). +Language, framework, library, and security rules use directory indexes plus focused topic files. Their generated Claude skills expose each focused rule separately; the index skills also include the references for contextual lookup. See [Configuration](configuration.md). Skills guide a task when needed; their availability does not require a full review, build, or test suite after every change. The shared Verification rules govern proportional checking, including when generic skill workflows call