A Practical Guide to AI Coding Agents: 5 Core Mechanisms You Need to Master

Introduction: Using the Agent ≠ Using It Well

Over the past couple of years, LLM-based AI coding agents have evolved from code-completion plugins into autonomous engineering partners that can read code, edit files, and execute commands. Many developers favor CLI-based (command-line) coding agents for a practical reason: they tend to have friendlier support for domestic models than comparable commercial tools. You can connect a model vendor’s API directly, or switch the underlying model through any service that implements the OpenAI-compatible API protocol. Combined with highly competitive pricing from those model providers, these agents can easily become the go-to tool for everyday development.

Still, many people use them for a long time without getting past the “agent as chat box” stage. They rework frequently as soon as requirements get complex. They lose key context in the second half of long conversations. They get inconsistent code style from one generation to the next. And when working in a team, everyone ends up doing their own thing. The root cause isn’t model capability. It’s not understanding how the agent actually runs.

To really get value out of an agent, you need to master five core mechanisms: Context, project rule files, Hooks, Skills, and Subagents. Using how CLI-based AI coding agents work as a thread, this article breaks down each mechanism and shows you how to move from “using it” to “using it well”.

---

1. The Context Window: It’s More Than Your Chat History

Many developers think the agent’s context window is just “my conversation history with it.” That’s only one-seventh of the picture.

1.1 Seven Types of Content in Context

According to the official documentation for CLI-based AI coding agents, a session’s context window typically holds the following seven types of information at the same time:

Category	Description	Typical Footprint
System instructions	The agent’s own operating rules, behavior guidelines, and tool definitions (Read/Write/Bash, etc.)	Fixed overhead, always present
Conversation history	Your multi-turn inputs and the agent’s outputs	Grows linearly with the conversation
File contents	Source files the agent has read or edited	A single large file can take up thousands of tokens
Command output	Results of terminal commands, such as build logs and test results	Full logs often reach tens of thousands of tokens
Project rules	Project-level persistent instructions (convention files)	Re-injected on every session
Auto memory	Learning records the agent saves across sessions (paths, preferences, etc.)	Loaded on demand
Loaded skills	The full skill instruction text injected once a skill is triggered	Hundreds to thousands of tokens per skill

There’s an easy-to-miss detail here: file contents and command output take up far more room than conversation text. One full build log or one cat of a large file can eat up a sizeable chunk of the window. So if you think, “I’ve barely said anything, why is my context already full?” you’re not imagining it.

1.2 What Happens When the Context Fills Up: Two-Stage Reclamation

As token usage approaches the limit, the context management module reclaims space in two stages:

1. Clearing old tool outputs: It first discards earlier file-read results and command outputs. They are large, less relevant as time goes on, and can always be recovered by reading again.
2. Summarizing the conversation history (Compact): It condenses multiple turns of interaction into a summary that keeps the conclusions and drops the process.

1.3 The Real Cause of “Memory Loss”: Compaction Loses Information

Summary-based compaction is a double-edged sword. Suppose in turn 3 you repeatedly insisted that “this module must use reactive programming,” and in turn 5 you locked in an architecture decision. After compaction, those points may be reduced to a vague “architecture options discussed.” This is the root cause of agents “not following instructions” in long conversations. The agent isn’t slacking off; your key constraints really were compressed away.

There are three layers of countermeasures for this problem, each covered below:

• Layer 1: Write constraints that must stay in effect long-term into a project rule file.
• Layer 2: Trigger compaction manually and tell the agent what to focus on.
• Layer 3: Hand complex workflows to hooks for deterministic enforcement.

A typical context management flow can be simplified as:

if remaining_tokens < threshold:
    clear earlier tool outputs (file contents, command results)
if still not enough:
    summarize the conversation history
    # Project rule files are not compacted; they are re-injected on every session

---

2. Project Rule Files: Turn Conventions into “Long-Term Memory”

If what you say on the fly gets compacted away, move it somewhere that compaction can’t touch. That’s exactly what project rule files are for.

2.1 What They Are and Where They Live

CLI-based AI coding agents automatically look for and load project rule files at startup. The conventional file name is CLAUDE.md (a similar tool uses AGENTS.md). These files support multiple levels of configuration:

• ~/.claude/CLAUDE.md: User level. Shared across all projects, good for personal preferences such as “reply in Chinese” or “write code comments in Chinese.”
• <project root>/CLAUDE.md: Project level. Committed with the code repository and shared by the team, good for the tech stack, directory conventions, and commit standards.
• <subdirectory>/CLAUDE.md: Module level. Loaded only when the agent reads files in that directory, good for local rules in large repositories.

Key behavior: its content is re-injected after every compaction, which makes it naturally immune to “memory loss.”

2.2 Four Tips for Writing Effective Rule Files

Many people turn their rule files into “wish lists,” yet the agent still doesn’t follow them. The problem is usually in how they’re written:

1. Give instructions, not background. Delete phrases like “please follow” and write things like “you must run npm test before committing.”
2. Be specific, not abstract. “Code should be elegant” imposes no real constraint, whereas “use function components; class components are forbidden” actually works.
3. Keep it short. Rule files take up context too. Keep them within a few hundred lines and move the details into subdirectory files.
4. Let the agent help you write them. When you start with a new repository, use the /init command to have the agent scan the codebase and generate a first draft, then revise it by hand. It’s much more efficient than writing from scratch.

Here’s an example CLAUDE.md you can use as a reference:

# Project Overview
E-commerce order service built with Spring Boot 3, MyBatis, and Redis.
## Common Commands
- Build: `mvn clean package -DskipTests`
- Test: `mvn test -Dtest=OrderServiceTest`
- Code check: `mvn spotless:check`
## Coding Standards
- Every new API endpoint must have its API documentation under `docs/api/` updated in the same change
- Every database change must include a rollback script
- No business logic in Controllers
# Context Compaction Retention Rules
When compacting the conversation, you must keep the following:
- Technology choices the user explicitly requested, along with the reasons
- Outstanding to-do items and their current progress
- Known error messages and debugging conclusions

That final “Context Compaction Retention Rules” section is an advanced technique: explicitly tell the agent what must not be lost during compaction. It can’t guarantee completely lossless results, but it significantly improves the odds that key decisions survive.

2.3 Use /compact to Highlight What Matters

When context is nearly full, you don’t have to wait for the system to compact it automatically. You can run /compact yourself and tell the agent what to focus on:

/compact focus on the field changes and compatibility conclusions from this API change

The benefit is that you understand better than the agent what information matters, so stepping in keeps compaction losses to a minimum. After compaction, you can also use /rewind to roll back to an earlier checkpoint and correct the direction if things have gone off track.

---

3. Hooks: Hand Workflow Constraints to Deterministic Code

Rules and prompts ultimately depend on the model choosing to follow them. Hooks hand key checks to deterministic scripts instead. It’s the leap from “suggestion” to “enforcement.”

3.1 How Hooks Work: Event-Driven

Hooks run Shell scripts you’ve set up in advance at key points in the agent’s lifecycle. Common events include:

Event	Triggered When	Typical Use
PreToolUse	Before a tool is invoked	Block dangerous commands, validate operations on sensitive files
PostToolUse	After a tool call finishes	Auto-format code, run lint, update indexes
UserPromptSubmit	After you submit input, before the model processes it	Inject additional context, filter sensitive terms
SessionStart	When a session starts	Load project state, pull the latest code
Stop	When the agent is about to finish responding	Force tests to run, generate a change summary

The interception capability of PreToolUse is especially important. By returning a specific exit code or JSON structure, a hook script can stop the agent from carrying out an operation and send feedback back so the agent can correct itself. For example, you can forbid edits to .env, forbid rm -rf, and forbid pushing to main without confirmation.

3.2 Example: Automatic Tests Before the Agent Finishes

Hooks are configured in .claude/settings.json, which the team can share. The example below shows a typical setup:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./.husky/block-dangerous-cmd.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $CLAUDE_FILE_PATHS"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "npm test -- --silent",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

This configuration does three things. Files are formatted automatically after each edit. Tests run automatically when the agent is about to wrap up. If the tests fail, the failure details are sent back to the agent so it can keep fixing them. Code quality assurance moves from “relying on self-discipline” to “enforced by the system.”

Note: Hook scripts run in your local Shell. Always review where they come from before using them, especially configuration files shared by third parties, to avoid pulling in malicious commands.

---

4. Skills: On-Demand “Professional Operating Manuals”

4.1 What Is a Skill

A skill is a bundle of instructions, scripts, and reference materials that packages specific workflows the agent doesn’t perform by default. Examples include “generate API documentation from the company template” and “run standard database migration checks.” In essence, it’s an SOP (standard operating procedure) written for the agent.

Skills are usually stored in the ~/.claude/skills/ (user level) or .claude/skills/ (project level) directory. Each skill gets its own folder, and the core is a Markdown instruction file plus optional supporting resources:

skills/
└── api-doc-gen/
    ├── SKILL.md          # Required: metadata + operating steps
    ├── template.md       # Optional: document template
    └── scripts/
        └── extract-routes.py  # Optional: helper script

A SKILL.md file starts with metadata in the header, followed by the instruction body:

---
name: api-doc-gen
description: Generate documentation for new API endpoints using the team
  template. Use when the user asks to "write API docs", "add docs", or
  "document an endpoint".
---
# API Documentation Generation
## Steps
1. Locate the new or modified Controller methods
2. Extract the request path, parameters, and response structure
3. Generate Markdown following the format in template.md
4. Write the result to the docs/api/ directory

4.2 Progressive Disclosure: Why Skills Are Easy on Context

The most elegant part of the skill design is progressive disclosure:

1. When a session starts, only each skill’s name and description (usually a few dozen tokens) are loaded into context, so the agent knows which capabilities are available.
2. When your request matches a description, the agent reads that skill’s full instructions and injects them into the context.
3. Templates, scripts, and other resources referenced by those instructions are loaded further on demand.

Thanks to this design, the always-on overhead of “installing a hundred skills” is almost the same as “installing none,” while the agent’s capabilities stay easy to extend.

4.3 Skills vs. Rule Files vs. Subagents

It’s easy to mix up the three. The deciding factor is how they’re triggered:

Mechanism	Trigger	Best For
Project rule file	Always active	Team-wide standards, tech stack descriptions, command lists
Skill	Triggered on demand when the description matches	Multi-step workflows with a clear procedure, such as release checks or documentation generation
Subagent	Explicitly delegated by the main agent	Large tasks that need isolated context or parallel processing

---

5. Subagents: Give the AI “Its Own Team”

5.1 Core Principle: Context Isolation

When tasks get complex, a single main agent working alone runs into two problems. First, its context fills up with large amounts of intermediate work. Second, a single prompt struggles to cover roles as different as architecture design, test writing, and security review.

Subagents solve this by outsourcing the work. The main agent delegates to one or more specialized subagents based on the task type. Each subagent does its work in its own independent context window and returns only a summary of its conclusions to the main agent.

This brings three direct benefits:

• Context isolation: A subagent can comb through dozens of files while the main window holds only a short summary of conclusions, keeping the main context clean.
• Role specialization: Each subagent has its own system prompt, tool permissions, and model choice. For example, a testing agent can be restricted to reading and writing only the test directory.
• Parallel execution: Independent tasks that don’t depend on each other can be delegated at the same time, cutting overall time.

5.2 Built-In Subagents and Custom Ones

CLI-based AI coding agents usually come with a set of ready-to-use subagents, such as Explore for code exploration and general-purpose for general tasks. They also let you define your own. Custom subagents live in the .claude/agents/ directory, one Markdown file per subagent, with a structure similar to a skill:

---
name: db-migration-reviewer
description: Review database migration scripts. Use when reviewing SQL
  changes, migration scripts, or rollback plans.
tools: Read, Grep, Glob, Bash
model: sonnet
---
You are a database review expert responsible for reviewing migration scripts.
Checklist:
1. Does it include a rollback script?
2. Is there a lock-table risk assessment for large tables?
3. Are index changes validated with an execution plan?
4. Are field type changes compatible with older application versions?

The main agent starts a delegation through the “task tool,” for example:

{
  "task": "Review all newly added scripts under src/db/migration/ and output a list of issues",
  "subagent_type": "db-migration-reviewer"
}

In the task description, you can define the scope explicitly, for example “search with Grep only; don’t read entire files,” to keep the subagent on the path you want.

5.3 Going Further: More Advanced Multi-Agent Patterns

Beyond subagents, more systematic multi-agent collaboration patterns have emerged in the industry:

• ReAct pattern: The agent loops between “reasoning, acting, and observing,” using the result of each step to decide the next one. It’s the basic single-agent loop.
• Plan-and-Execute: One planning agent first breaks the goal into a complete task list, which is then assigned to multiple execution agents, and the results are gathered at the end. It suits large tasks with clear requirements whose steps can be broken down in advance.
• Multi-agent orchestration: Multiple role-based agents work together in a “supervisor and specialists” structure. The supervisor splits up tasks and merges the results, while the specialists handle their own domains.

These patterns bring agent performance on complex engineering tasks close to that of a small development team.

---

6. Advanced Capabilities: Let the Agent “See” the Whole Project

The five core mechanisms above address “how to get reliable use out of the agent.” Real-world engineering often combines them with the following capabilities:

• RAG (retrieval-augmented generation): A large repository can’t be stuffed into the context in full. A code indexing service handles semantic search and feeds only the relevant snippets to the agent. Some tools offer a “codebase index” feature that stores repository metadata encrypted in the cloud and downloads only matching snippets when a search is run.
• Memory: Persists project paths, your preferences, and known pitfalls across sessions, so you don’t have to explain them all over again every time.
• Web search: Lets the agent look up the latest documentation for frameworks, which helps reduce “hallucinated APIs.”
• Context protocol integration: Standard protocols such as MCP connect the agent to external data sources like databases, internal wikis, and monitoring platforms, extending its reach beyond the IDE.
• Terminal / IDE dual entry points: Besides the terminal, some tools also come as IDE plugins that fit seamlessly into your existing workflow.

One point is worth stressing: model capability sets the ceiling, while engineering mechanisms set the floor. Even with domestic models such as DeepSeek or Kimi, once you’ve set up these four layers (rules, hooks, skills, and subagents), a CLI-based AI coding agent can consistently produce high-quality code.

---

Conclusion

Back to the question at the start: why do some people get a huge boost from AI coding agents while others keep running into problems? The difference lies in how deeply they understand the five core mechanisms:

1. Context: Only by knowing what’s inside the window can you control how it’s used up and what’s kept.
2. Rule files: Move long-term constraints out of “conversations that get compacted” and into “project conventions immune to compaction.”
3. Hooks: Turn “hope it follows the rules” into “it can’t get past this check unless it does” with deterministic validation.
4. Skills: Package repetitive, complex workflows into reusable professional manuals that load on demand without any always-on overhead.
5. Subagents: Use context isolation and role division to take the agent from working solo to working as a team.

These five build on each other to form a complete “context engineering” methodology. As a next step, start with a real project: write a solid CLAUDE.md, set up two or three hooks, and package one skill. Turn these mechanisms into engineering assets for your team, then gradually expand into more complex multi-agent scenarios.