AI-SDLC in Practice: A Guide to the Six Agent Host Capabilities

1. Agent = Model + Harness: Know What the Host Already Does

A coding agent can be split into two layers: the Model, which does the reasoning, and the Harness, which handles everything around the model.

A harness typically covers:

• The conversation loop and multi-turn state management
• Issuing tool calls and feeding results back
• Assembling and compacting the context window
• Spawning and reclaiming subagents
• Permission confirmation and operation interception
• Connections to external systems

The harnesses shipped by today’s mainstream hosts (including the two dominant coding tools) are already fairly complete, so there is little reason to rebuild these parts. What a team genuinely has to supply on its own is only two things:

• A CLI toolchain: drives the workflow and gives the agent helper commands for validation, checklist generation, and similar tasks
• A knowledge base: captures architecture conventions and coding rules so the agent produces better code

Before writing anything, it is worth clearing away three common misconceptions.

Misconception 1: swapping hosts blindly, before you understand them. Switching tools is cheap; re-learning where the boundaries of the six capabilities actually sit is not. The safer path is to read the official documentation first, write down the entry conditions for each capability, and only then make a selection.

Misconception 2: treating the tool as a code generator that exists to “let AI write a first draft.” That uses only the Model’s capability. Context, permissions, and extension mechanisms all sit idle, and the code that comes out rarely survives review.

Misconception 3: treating the agent as omniscient, with no context supplied and no boundaries set. An agent does not automatically know about APIs released after its knowledge cutoff, or about conventions internal to your team. Those are precisely what the harness’s context mechanisms and external connections exist to supply.

The value of AI-SDLC is not in installing more plugins. It is in making sure every stage gets exactly the context, tools, and permissions it needs.

2. The Core Harness Constraint: The Context Window Is a Zero-Sum Resource

The most important thing a harness does is decide what goes into the context window sent to the model on each turn. System prompts, project rule files, tool definitions, Skill listings, message history, tool results, and file contents all compete for the same space.

Published host documentation exposes a number of budget figures that fall into a few categories:

• When project rule files are loaded, multiple files share a total byte cap—often only a few dozen KiB by default—and anything over the limit is skipped
• Skills are only lightly registered at session start, typically consuming a single-digit percentage of the window; their bodies are read in only when actually needed
• Community practice commonly recommends keeping an individual rule file within roughly one to two hundred lines
• Overly long Skill descriptions get truncated

These numbers all send the same signal: the host itself enforces strict size limits on each block of content in the window. The job of AI-SDLC is to use the capabilities the harness provides so that at every stage the window holds only what that stage needs.

Every byte in the window competes with everything else. A simplified budget sketch makes the shape of it clear:

Context window budget (illustrative)
├── System prompt + tool definitions     Fixed overhead; compress first
├── Project rule files (resident)        Keep to a single main file
├── Skill description list (resident)    Names and one-line descriptions only
├── History + tool results               Clear as soon as the task ends
└── Material the current task needs      Target: the largest share

Two practical principles decide what to load:

1. Split by task. The requirements-understanding stage should not carry the previous task’s build logs, and a review role should not see a development role’s trial-and-error trail.
2. Refresh by freshness. Volatile information—version numbers, API paths, owners—should be queried live when a tool runs, not hard-coded into rule files.

The less irrelevant content in the window, the more focused the agent stays and the steadier its judgment becomes.

3. The Six Capabilities: Where Each Acts on the Window

The six capabilities are worth comparing side by side because together they cover different points in the context lifecycle. By how they affect the context window, they fall into four groups:

Capability	Stage of action	Effect on the context window	Typical use
Project rule files	Session start and every request	Resident	Architecture constraints, coding standards
Skill	When a task matches	Description resident; body loaded on demand	Reusable procedures and templates
Subagent	Task dispatch and result return	Separate window; only conclusions come back	Investigation, review, wide-scope search
Hook	Fixed lifecycle moments	Adds or intercepts content	Automated checks, format checks, context injection
MCP	When tools are called	Tool definitions resident; results on demand	Connecting external systems and data sources
Permissions and sandbox	Every tool execution	None—enforced outside the window	Restricting dangerous operations and resource access

3.1 Project Rule Files (AGENTS.md, CLAUDE.md, and similar): In the Window Every Turn

A rule file in the project root enters the window at session start and is carried on every subsequent request. When context is compacted, it is not summarized together with the conversation history; it is put back verbatim. Mainstream hosts generally re-inject it from disk after compaction, and some open-source implementations do the same. This design keeps conventions from being “compacted away” as the conversation grows.

The exception is the on-demand portion. Taking the common design in mainstream hosts:

• Subdirectory rules: a rule file in a subdirectory loads only when the agent reads or writes files in that directory
• Path-scoped rules: rules declared with paths: apply only to tasks touching that path
• Imports: a rule file can pull in other files via @path

During compaction, on-demand rules are folded into the summary, and whether they come back depends on whether the load condition fires again. So keep the resident portion lean, and split the on-demand portion “by path, each covering its own slice.”

A sketch of the structure:

# Root rule file (resident; keep under ~150 lines)
## Project overview      # One line each on domain, stack, and layout
## Architecture rules    # Layering, dependency direction, prohibitions
## Coding standards      # Naming, error handling, log format—only the critical few
## Common commands       # Build, test, lint—fixed forms the agent can call directly
# Subdirectory rule files (loaded on demand)
frontend/AGENTS.md        # Triggered only by frontend-component tasks
docs/spec/*.md            # Rules with paths: docs/spec/**, triggered only by spec tasks

3.2 Skills: Enter the Window Only When Used

A Skill is a packaged, reusable unit of work, usually made up of a name, a description, and a body: the description participates in routing, and the body holds the steps and templates.

Its value is threefold:

• Loaded on demand: at session start only the description is registered; the body is read in only when a matching task appears, so it costs almost nothing resident
• Easy to iterate: when a convention changes, update the Skill rather than rewriting rule files
• Composable: several Skills can be chained in one task to form a stable procedure

Practice notes: write the description so it makes clear when to use it; keep only the necessary steps and templates in the body—procedural steps belong in a Skill. Also respect the host’s limits on description length and count; more is not better.

# Skill metadata sketch (actual format follows the host documentation in use)
name: api-change-review
description: Use when a task involves adding endpoints, changing fields, or adjusting compatibility; produces a compatibility review checklist

3.3 Subagents: Open Another Window and Clear Out the Main Context

A subagent is a lightweight agent with its own context window, its own system prompt, and its own toolset. The main agent dispatches a task; the subagent executes it and returns only a summary of conclusions. This is the key design for resolving context contention:

• Trial-and-error trails, log output, and search results stay in the child window and never pollute the main one
• Roles can specialize—code review only, test generation only—without bleeding into one another

Good fits: search across many modules, dependency impact analysis, code review from an independent perspective, and consolidating large batches of test results.

3.4 Hooks: Intervening at Fixed Moments

A hook is a command or script registered on a lifecycle event. Common moments include session start, user prompt submission, before and after a tool call, when the agent stops responding, and before and after context compaction.

Hooks solve three kinds of problems:

• Pre-interception: block a dangerous command before it actually runs
• Post-completion: append test output or check reports after a tool returns
• Context refresh: put key facts back into the window after compaction

A sample configuration (field naming varies by host):

{
  "hooks": {
    "post_tool_use": [
      { "matcher": "edit|write", "command": "make check-staged" }
    ],
    "pre_compact": [
      { "command": "make export-context-facts" }
    ]
  }
}

3.5 MCP: Pulling Content Into the Window From Outside

MCP (Model Context Protocol) is an open protocol for connecting external tools and data sources to an agent in a standardized way. Once connected, external systems are exposed to the agent as tools. Typical uses: querying requirement items, searching architecture documents, reading logs and monitoring metrics, and operating the code hosting platform.

Account for the cost up front: every external system you connect keeps its tool definitions resident in the window, so the more tools, the larger the fixed overhead. Two principles follow: prefer on-demand queries over bulk pulls, and default to read-only with least privilege.

3.6 Permissions and Sandboxes: Enforced Outside the Window

Permissions and sandboxes are the only capability that never enters the context window, yet they determine how far the other five can go. Permissions decide whether an agent needs human confirmation before a class of operation and which operations are outright forbidden; a sandbox confines actual impact through isolation of filesystem scope, network egress, and process resources.

Its relationship with the window is “tight inside, tighter outside”: the window decides what the agent sees, permissions decide what the agent can do. When the two disagree, align them with a dual checklist—every principle written into the rule files must have a corresponding entry in the permission configuration.

4. The Five AI-SDLC Stages: How the Capabilities Combine

Stage 1: Requirements Understanding

• Rule files: inject the domain glossary and an acceptance-criteria template
• MCP: query requirement items and change history on demand
• Subagent: independently check the requirement description for ambiguity and gaps
• Skill: provide the clarification-question checklist and the spec-document template

The point of this stage is a clean window. Do not let the agent carry the previous task’s context into requirements work, or it will treat the old design as the default premise.

Stage 2: Architecture Design

• Rule files: state layer boundaries, dependency direction, and prohibitions
• MCP: connect architecture documents, the service inventory, and interface definitions
• Subagent: evaluate several candidate designs in parallel, with the main agent consolidating the comparison
• Hook: automatically check template completeness when the design document is written

Stage 3: Implementation

• Rule files: coding standards, commit conventions, and a common-mistakes list
• Skill: step-by-step procedures and code templates for common change types
• Subagent: wide-scope code search and impact analysis
• Permissions and sandbox: writes allowed in the working directory only, no direct pushes to protected branches, network access opened on demand

Stage 4: Review and Testing

• Subagent: an independent review role that sees only the diff and the rules, not the development team’s trial and error
• Hook: run format checks and unit tests automatically after tool calls
• MCP: pull test cases, historical defects, and static-analysis results

Stage 5: Release and Operations

• Permissions: tightened to read-only, with the release action handed to the pipeline
• Sandbox: any production-related operation must run in an isolated environment
• MCP: mount only read-only channels such as logs and monitoring
• Hook: generate a retrospective record when the task ends, distilled into a new Skill

One cross-stage lesson: clear the task-level context at the end of every stage before entering the next.

5. Supporting Two Mainstream Hosts From One Codebase

Host file naming, configuration formats, and event definitions differ. Supporting both means adding an adaptation layer at the project level. A workable approach:

5.1 Single Source of Truth

Keep conventions and procedures together in an ai/ directory, then point each host’s convention file at it:

ai/
├── rules/             # Rule fragments split by domain
│   ├── architecture.md
│   ├── coding.md
│   ├── frontend.md    # Loaded on demand by subdirectory
│   └── spec.md        # Applies only to spec tasks
├── skills/            # Host-agnostic Skill bodies
├── hooks/             # Host-agnostic validation scripts
└── policy/            # Permission policy checklist

The two hosts’ convention files stay in the same shape: the root file holds “project overview + @ai/rules/architecture.md + @ai/rules/coding.md,” and each subdirectory imports its matching fragment. Change a rule once and both sides pick it up.

5.2 Mapping Layer

Maintain a capability mapping table that names what carries each capability in each host:

Capability	Host A	Host B	Common location
Project rule files	Root convention file	Root convention file	ai/rules/
Skill	Skill directory	Custom command	ai/skills/
Subagent	Subagent config	Custom command + isolated task	ai/subagents/
Hook	Lifecycle hook	Notification and prompt mechanism	ai/hooks/
MCP	Standard connector config	Adapted to the host’s integration method	Unified tool inventory
Permissions and sandbox	Allow/deny list + sandbox mode	Execution approval policy	ai/policy/

5.3 Minimum Common Set

Make capabilities that both hosts have and whose behavior is closest the baseline, and put anything available on only one side into an extension layer. For example, subagents are native configuration in one host; in the other they can first be emulated with “a separate task directory + a custom command” that returns only a conclusion summary.

5.4 Funnel Into the CLI

Express the checks as host-agnostic commands, for example:

make ai-check-rules     # Validate rule-file line counts and reference paths
make ai-check-skills    # Validate Skill description length and body completeness
make export-context-facts   # Export key facts for re-injection after compaction

Each host’s hooks only need to call these commands, which isolates platform differences in a thin layer of glue code.

5.5 CI Regression

Fix a set of “golden cases” in the continuous integration pipeline: one full requirements-to-commit flow, one context-compaction scenario, and one permission-interception scenario. Run each on both hosts, record every behavioral difference in the mapping table, and state explicitly which side is authoritative.

6. Implementation Checklist

When standing up the AI-SDLC pipeline, work through this list:

• Rule files: the main file’s length is controlled, subdirectory and path rules each cover their own slice, and reference paths can be validated
• Skills: each description makes the trigger condition clear, no outdated commands remain in the body, and description length stays within the host’s limit
• Subagents: each has an independent toolset and an explicit output template, and returns conclusions only
• Hooks: pre-interception covers dangerous commands, and there is a mechanism to put key facts back around compaction
• MCP: the tool inventory is reviewed regularly, read-only comes first, and tokens are requested with least privilege
• Permissions and sandbox: deny by default and allow on demand, read-only in production, release handed to the pipeline
• Project structure: a single source of truth for conventions, both hosts aligned through a mapping layer, and check logic funneled into host-agnostic commands
• Supporting infrastructure: artifacts stored in a single cloud-hosted artifact repository; the pipeline runs on a container platform, with logging, monitoring, and alerting exposed as read-only channels. This keeps conventions, pipeline scripts, and the knowledge base distributed consistently across the team and reduces interference from local environment differences

One more recommendation: turn every “the agent got this wrong” finding from a retrospective into a rule or a Skill. That gives AI-SDLC an evolving “engineering memory”—the longer you use the six capabilities, the more that memory is worth.