Four Layers of AI Coding Assistant Customization: Memory, Hooks, Skills, and Subagents

1. The Problem: Why Prompts Alone Are Not Enough

Most teams start out with the same pattern: put the conventions in the prompt. Every new session begins with the same briefing — the tech stack, the directory layout, the commit rules, and the one pattern nobody is allowed to use. It has three structural weaknesses.

First, it is easy to forget. The model’s context window is limited, and the weight of early instructions decays as the conversation grows. Adherence to conventions drops with every turn.

Second, it is not verifiable. A prompt is advisory input. The model can follow it or ignore it, and there is no way to prove after the fact that a given rule was actually enforced.

Third, it is not reusable. The same project knowledge is passed around verbally by every team member on every machine and never accumulates as an organizational asset.

The industry’s answer is to layer the customization. Current coding tools generally offer four mechanisms. They are not a feature checklist but a stack, ordered from the bottom up with increasing enforcement strength:

Layer	Mechanism	Category of problem	When it applies	Enforcement
Memory	Persistent instruction files	Context needed in every session	Loaded automatically at session start	Soft (advisory)
Constraints	Lifecycle hooks	Rules that must run and are not open to discussion	Forces commands at specific events	Hard (blocking)
Capabilities	Reusable skill packages	Complex processes that must be reproduced fully and correctly	Loaded on demand when the scenario matches	Medium (process guidance)
Division of labor	Subagents	Subtasks interfering with the main task, context bloat	Isolated context	Medium (structural isolation)

Understanding how the four layers relate is the key: memory governs “does it know,” constraints govern “was it done,” skills govern “how to do it right,” and subagents govern “where to do it.” The rest of this article works through each layer.

2. Memory Layer: Persistent Instruction Files

2.1 What it solves

At the start of every session, the assistant reads agreed-upon Markdown configuration files automatically — usually resolved hierarchically from the project root, parent directories, and the user’s global directory. It is effectively an onboarding document for the model: it holds the project baseline before it does anything.

2.2 What to write, and what not to

The rule of thumb: record what the model cannot cheaply infer from the code, rather than restating the code.

Worth writing:

• Tech stack and version constraints: language version, major framework version, dependency types that must not be introduced
• Directory and layering conventions: where business logic, data access, and DTOs live
• Build and verification commands: “checks that must pass after changing code”
• Team red lines: never edit generated files directly, never add a synchronous blocking call in a core path
• Testing policy: which tests a new feature must add, the minimum coverage

Not worth writing:

• Long API documentation — it belongs in an on-demand skill package
• Implementation detail that duplicates the code — code changes and documentation drifts
• Aspirational rules with no enforcement. “Keep the code elegant” has no grip on a model

2.3 Organizing it: progressive disclosure

No single file should be long. It is loaded in every session, which makes it a constant context cost. The recommended approach is layering with on-demand references:

project-root/
  MEMORY.md                 # Global baseline; keep it under 100 lines
  docs/
    architecture.md         # Architecture decision records; referenced on demand
    api-conventions.md      # API conventions; referenced on demand
  backend/
    MEMORY.md               # Local conventions for the subdirectory; applied when you enter it

The main file offloads large sections through reference syntax and expands them only when needed. The baseline stays lean, the detail stays reachable. The test is simple: if a section runs longer than three screens, it does not belong in the memory layer.

2.4 Common anti-patterns

• Writing the memory file as a wish list; too many rules and the model trades one off against another
• Pasting the full team wiki in, so the context budget is consumed by documentation
• No version control and no synchronization with the code, which eventually makes the file a source of misleading information

3. Constraint Layer: Lifecycle Hooks

3.1 How it differs from the memory layer

Memory persuades. Hooks enforce. At fixed points in the assistant’s lifecycle — before a session starts, before a tool call, after a tool call, before a session ends — the runtime forcibly triggers an external command, and the return value determines what happens next: whether to proceed, whether to block, whether to feed information back to the model.

This means hooks do not depend on the model’s cooperation; they are deterministic. Any rule that must hold belongs in this layer.

3.2 Typical use cases

Write gates. After any file write, run formatting and static checks automatically. Style problems get eliminated at the moment they are created instead of waiting for review.

Blocking sensitive operations. Match destructive command patterns before execution — force push, branch deletion, recursive delete, commit with checks skipped — and on a match, block it and return the reason to the model.

Tests before commit. Attach unit tests and type checks to write events. The model receives the failure output and fixes it itself, forming an automatic loop.

Audit and observability. Report every triggered event to a log service to measure rule-violation rates and evaluate the quality of the assistant’s output. In enterprise adoption this step carries the most value, because it turns “the AI’s code seems fine” into measurable metrics.

3.3 Configuration example

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "format && typecheck",
        "onFailure": "block",
        "feedbackToModel": true
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "./scripts/guard-destructive.sh",
        "onFailure": "deny"
      }
    ]
  }
}

3.4 Design principles

1. Fast. Hooks sit on the critical path; anything taking more than a few seconds visibly slows the interaction, so heavy work should be asynchronous or cached.
2. Idempotent. The same hook may fire more than once. Do not assume a single execution.
3. Make the failure policy explicit. Block or warn only — declare it in the configuration; do not rely on default behavior.
4. Readable output. What goes back to the model should be an actionable error summary, not thousands of lines of raw logs, or it will crowd out the context.
5. Few and forceful. Keep the hook count in the single digits, and tie each one to a real rule that has actually been violated.

4. Capability Layer: Reusable Skill Packages

4.1 What a skill is

A skill packages “the standard operating procedure for a class of task” as a bundle of resources: a description of when to use it, a detailed step-by-step document, and optional helper scripts and template files. Its core design is progressive disclosure — at startup the assistant loads only the skill’s name and trigger description (negligible cost), and reads the full body and bundled resources only when the task matches that description.

This solves two pain points of the memory layer: it keeps all internal knowledge from being stuffed into the baseline file, and it ensures complex processes are executed completely and correctly instead of being simplified from memory.

4.2 Recommended structure

skills/
  release-hotfix/
    SKILL.md            # When to use + step-by-step process + verification checklist
    templates/
      changelog.tpl
    scripts/
      verify-version.sh
  migrate-to-new-sdk/
    SKILL.md
    references/
      mapping-table.md  # Mapping from old interfaces to new ones

4.3 Deciding the boundary: when to make it a skill

• The process has more than 5 steps and the order cannot be changed at will: releases, rollbacks, data migrations
• It requires consulting an external mapping table or reference document: framework upgrades, protocol compatibility work
• The same process keeps getting taught verbally by different team members
• The process includes a checklist with items that must be confirmed one by one

By contrast, “use camelCase” belongs in the memory layer, and “always run tests before any commit” belongs in the constraint layer. Memory holds facts, hooks hold red lines, skills hold processes.

4.4 Maintenance

Skills are assets, so they need version control and a named owner. The description must be precise: too broad and unrelated tasks trigger it, too narrow and it is never loaded. After rollout, watch the trigger rate in the logs and keep calibrating.

5. Division of Labor: Isolated Execution with Subagents

5.1 What it solves

The main conversation’s context is the scarcest resource. When the assistant walks through a hundred files to answer one small question, the flood of search results and intermediate reasoning occupies the main context permanently and degrades everything that follows. The idea behind subagents is simple: dispatch exploratory, noisy subtasks into an independent context and bring only the conclusion back to the main thread.

5.2 Where it applies

• Broad code searches: “which modules read this config item” — return the conclusion, not every file’s contents
• Independent review: let a subagent inspect the changes from a reviewer’s perspective, free from the preconceptions formed during implementation
• Diagnosing test failures: iterate in an isolated environment and report back the root cause and the fix
• Parallel bulk changes: assign unrelated modules to multiple subagents running at the same time

5.3 Design points

1. Tasks must be narrow and bounded. Subagents suit work with a clear goal that can be verified independently; they are a poor fit for requirements that need repeated clarification with the user.
2. Return structures must be compact. Agree on a format — conclusion plus key file paths plus risks — so process logs are not all fed back into the main context.
3. Constrain permissions. Grant a subagent only the minimum tool set the task requires. It is a safety measure, and it also reduces misoperation.
4. Avoid recursive nesting. Subagents spawning subagents makes debugging costs climb sharply; generally limit nesting to one level.
5. Be careful with shared state. Multiple subagents modifying the same files in parallel will conflict, so divide write operations along non-overlapping boundaries by file or module.

6. How the Four Mechanisms Work Together

Take a request to add a new internal API and wire it into a downstream service. The four layers act in sequence:

1. At session start, the memory layer injects layering conventions, build commands, and dependency red lines. The assistant knows which directory to write in and what checks to run afterward.
2. The assistant recognizes this as a standard process, loads the matching skill package, and follows its steps and templates to generate the API, the DTOs, the unit tests, and the API documentation.
3. The scope is large, so the assistant dispatches subagents to run compatibility checks and review existing implementations in parallel, while the main context keeps only the conclusions.
4. After each file write, a hook runs formatting and type checks, and failure output goes back to the assistant for self-repair. Before the commit, a hook blocks any commit that skips validation.
5. Events from the whole process are written to the log service, producing a measurable execution record.

The value of this chain: conventions move from “humans reminding the model” to “the environment constraining the model.” When people rotate or teams collaborate across boundaries, the conventions do not decay.

7. A Rollout Roadmap

Do not roll everything out at once. The recommended sequence has four steps:

Step 1: memory only. Spend a week or two building the project baseline, watch how the quality of the assistant’s output changes, and identify the rules that still get violated after repeated reminders.

Step 2: hooks for high-frequency violations. Start with formatting and destructive-operation blocking — the fastest payoff and the lowest risk.

Step 3: extract skill packages. Document the processes that most depend on senior engineers’ experience — releases, upgrades, troubleshooting — as skills. This is where turning knowledge into assets pays off most.

Step 4: introduce subagents. Try them in search and review scenarios, and observe changes in context usage and task success rate.

Suggested metrics: the review rejection rate for convention-related problems, formatting rework counts, average interaction turns per task, context-overflow interruptions, and skill trigger accuracy. Without measurement, customization easily degrades into “a pile of files nobody maintains.”

If the team already runs cloud-based development toolchains, the execution records produced by hooks can be aggregated into a log service for unified analysis, with monitoring and alerting notifying the owner when anomaly rates rise. Build artifacts and skill packages can be versioned in object storage, and validation scripts can run on a container platform, decoupling convention checks from the local environment. These are generic infrastructure capabilities, independent of any particular tool choice.

8. Common Mistakes

• Mixing up the layers: writing a red line as a suggestion (wrongly placed in memory), or stuffing a long process into the baseline file (wrongly placed in capabilities)
• Configuration sprawl: hooks keep piling up, the interaction keeps slowing down, and the team eventually switches them off
• No version control: customization files scattered across personal directories, impossible to review or trace
• Add-only growth: rules are added and never cleaned up, so half the entries in the baseline file are obsolete six months later
• Ignoring the feedback loop: no one reads the logs or measures violation rates, so there is no way to tell whether the customization works