# System Engine Hooks, Rules, and Instruction Files

Different AI coding tools expose different customization mechanisms. Some are real lifecycle hooks that execute commands at fixed points in the runtime. Others are persistent instruction files that are added to the model context as guidance. These should not be described as the same mechanism.

## A. Claude Code CLI Hook (`.claude/settings.json`)

Claude Code supports lifecycle hooks in `.claude/settings.json`, including `UserPromptSubmit`. This event runs after the user submits a prompt and before Claude processes it.

A `UserPromptSubmit` command hook can:

- read the submitted prompt from JSON on stdin;
- write plain text to stdout, which Claude Code can add as context;
- return structured JSON to add `additionalContext`, set a session title, or block the prompt.

The following example injects architecture-adaptive execution guidance on every submitted prompt:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s\\n' '{\"hookSpecificOutput\":{\"hookEventName\":\"UserPromptSubmit\",\"additionalContext\":\"ARCHITECTURE-ADAPTIVE EXECUTION GATE ACTIVE\\n\\nWhen implementing or modifying a software project with a recognizable architecture, first identify the architecture, then choose the correct layer, slice, module, or adapter sequence for that architecture. Do not implement the full solution in one pass. For each step, present the plan and intended code layout first, then ask for explicit user approval before writing implementation code.\"}}'"
          }
        ]
      }
    ]
  }
}
```

Important limits:

- This is a Claude Code hook, not a universal AI-engine hook.
- It can add context or block a prompt, but it does not override higher-priority system, developer, policy, or runtime instructions.
- A bare `echo` hook may add context in Claude Code, but structured JSON with `additionalContext` is more explicit and less ambiguous.

## B. Codex Lifecycle Hooks (`.codex/hooks.json` or `.codex/config.toml`)

Codex has its own lifecycle hook system. Codex does not use `.cursorrules` or `.github/copilot-instructions.md` as hooks.

Project or user hooks should be configured in one of these Codex-supported locations:

- `.codex/hooks.json`
- `.codex/config.toml` with inline `[hooks]` tables
- user-level equivalents such as `~/.codex/hooks.json` or `~/.codex/config.toml`

For durable repository guidance in Codex, use `AGENTS.md`.

Example Codex hook:

```json
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "printf '%s\\n' 'ARCHITECTURE-ADAPTIVE EXECUTION GATE ACTIVE\\n\\nWhen implementing or modifying a software project with a recognizable architecture, first identify the architecture, then choose the correct layer, slice, module, or adapter sequence for that architecture. Do not implement the full solution in one pass. For each step, present the plan and intended code layout first, then ask for explicit user approval before writing implementation code.'"
          }
        ]
      }
    ]
  }
}
```

Important limits:

- Codex project-local hooks load only from trusted project `.codex/` configuration.
- Non-managed command hooks may require review and trust before they run.
- Hooks are lifecycle automation, not a guarantee that injected text overrides higher-priority instructions.

## C. Cursor and Copilot Instruction Files, Not Hooks

Cursor and GitHub Copilot support persistent instruction files, but these files are not executable lifecycle hooks and should not be described as intercepting every message or modifying the system prompt.

Use the appropriate instruction file for the tool:

- Cursor: prefer `.cursor/rules/*.mdc`, User Rules, Team Rules, or `AGENTS.md`.
- GitHub Copilot: use `.github/copilot-instructions.md`, `.github/instructions/*.instructions.md`, or `AGENTS.md` where supported.
- Codex: use `AGENTS.md` for durable repository guidance; use `.codex/hooks.json` or `.codex/config.toml` for lifecycle hooks.

Corrected instruction-file wording:

```markdown
# Architecture-Adaptive Layered Execution Guidance

Apply this guidance when implementing or modifying a software project with a recognizable architecture, including but not limited to:

- .NET Clean Architecture / DDD / CQRS
- Spring Boot multilayer architecture
- Vertical Slice Architecture
- Hexagonal / Ports and Adapters Architecture
- Onion Architecture
- Modular monoliths or similarly layered systems

## Core Rule

Do not implement the full solution in one pass.

First identify the project's architecture and determine the correct implementation sequence for that architecture. Then work layer by layer, slice by slice, module by module, or adapter by adapter as appropriate.

Before writing implementation code for each step:

1. State the detected architecture.
2. State the active layer, slice, module, or adapter being planned.
3. Present the intended file/code layout for that step.
4. Ask: "Do I have permission to implement this step now?"
5. Wait for explicit user approval before writing code.

## Architecture-Specific Sequencing Examples

For .NET Clean Architecture, DDD, or CQRS, prefer:

1. Domain
2. Application
3. Infrastructure
4. API / Presentation

For Spring Boot multilayer architecture, prefer:

1. Domain / Entity / Model
2. Repository / Persistence
3. Service / Application Logic
4. Controller / API
5. Configuration / Integration

For Vertical Slice Architecture, prefer:

1. One feature slice at a time
2. Request / Command / Query contract
3. Handler / Use case logic
4. Validation
5. Persistence or integration required by that slice
6. Endpoint / API exposure
7. Tests for that slice

For Hexagonal / Ports and Adapters Architecture, prefer:

1. Domain model
2. Inbound ports / use cases
3. Outbound ports
4. Application services
5. Driven adapters, such as persistence or external APIs
6. Driving adapters, such as REST controllers, CLI, messaging, or UI
7. Composition / dependency wiring

## Approval Gate

At every step, stop after the plan and ask for approval.

Do not generate implementation code until the user explicitly approves the current step.

## Scope Limits

Do not apply this process to trivial edits, documentation-only changes, formatting-only changes, dependency bumps, or isolated bug fixes unless the user asks for architectural sequencing.
```

Important limits:

- Instruction files guide model behavior; they are not command hooks.
- They are subject to each product's context loading, settings, trust model, and precedence rules.
- They should be written as repository guidance, not as claims about system-prompt injection.

## Bottom Line

The original Claude Code section was directionally valid but imprecise. The combined "Codex / Cursor / Copilot Prompt Hook" section was incorrect because it mixed real lifecycle hooks with persistent instruction files.