DEV Community: jamongx

The Four Layers of AI Engineering: From Prompts to Loops

jamongx — Mon, 21 Sep 2026 14:12:17 +0000

"Prompt engineering" has been a buzzword for a few years now. But if you look at what actually happens in practice, the prompt is only the innermost piece of the picture. I find it useful to think of AI engineering as four layers: prompt, context, harness, and loop. You start with the prompt at the center, and as you move outward, you deal with the information the model sees, then the code around the model, then the structure that keeps it running.

To be clear, this isn't an official industry taxonomy. The boundaries between layers overlap in places. But as a practical frame for deciding what to improve next in an AI system, it works well.

Definitions alone would be too abstract, so let's use the same scenario across all four layers: a system where an AI reviews the code every time a PR is opened. Watching the same goal change shape at each layer makes the role of each one clear.

1. Prompt Engineering

The innermost layer. This is what you type directly into the chat box:

what to ask
how to ask it
what to tell the model to avoid

Example. In the code review scenario, this is the stage where you paste a diff into a chat window and ask for a review.

A bad prompt:

Review this code.

A better prompt:

Review this diff.
- Check for potential bugs, then security issues, then performance, in that order.
- Skip style nitpicks. The linter handles those.
- If there's nothing wrong, just say "no issues". Don't invent problems to have something to say.
- For each finding, include the line number and a suggested fix.

Same model, same diff, but the focus and consistency of the output change quite a bit, because you've spelled out what to look at, what to ignore, and what shape the answer should take. The "don't invent problems" line matters more than it looks. Without it, the model sometimes flags trivial style issues or manufactures findings just to produce something.

This is also the layer where most people stay when they first use AI. The problem is that no matter how much you polish the prompt, if the model doesn't know your project, the output stays generic. Even with the prompt above, the model has no idea what error handling convention your team uses or where this function gets called from.

2. Context Engineering

Everything you provide beyond the direct request, so the model has something to base its judgment on. This is the second layer, wrapped around the prompt:

system instructions
reference documents
conversation history
good examples (few-shot)
expected output samples and writing rules

Example. In the code review scenario, context engineering means laying out the background the model needs instead of just throwing a diff at it.

[System instructions]
You are a senior reviewer on our team. Review against the conventions below.

[Reference: team conventions]
- Errors are returned as Result types, not thrown as exceptions.
- All DB access goes through the repository layer.
- External API calls must specify a timeout.

[Reference: related code]
- The relevant parts of the 3 files that call this function

[Good examples: 2 past review comments]
- The tone and depth of reviews our team actually writes

[Prompt]
Review this diff. (same as before)

Now the model judges the code against "our team's standards" rather than "generally good code." If someone throws an exception in a place where the team convention calls for a Result type, the model can flag that violation. That's a finding you'd rarely get without context.

CLAUDE.md in Claude Code is the classic example of this layer. Put your project structure, coding conventions, and build commands in there once, and you don't have to explain them in every prompt. You can also split rules by file type or directory with .claude/rules/, and provide documents like a DESIGN.md that captures design intent as context when it's needed. These files are persistent context: write them once, and they keep getting used. An implementation plan you write for a specific task, on the other hand, is closer to one-off context. If you keep the plan and its progress updated as you go, it helps the model keep track of the overall direction and where it currently is. Retrieving relevant documents with RAG and feeding them to the model is another typical form of context engineering. MCP is related to context in that it brings outside information to the model, but the part where you connect tools and manage calls belongs to the next layer, the harness. It's one of the clearest places where the boundaries blur.

So if a task depends on project-specific rules or related code, polishing the prompt only gets you so far. The model has never seen your codebase, and if you don't give it the information it needs, it has no choice but to fill the gaps with inference.

3. Harness Engineering

The harness is the code around the model call. Note that it wraps the call itself, not the model's output: assemble the prompt and context, call the model, validate what comes back, retry on failure. It's the software structure around that one cycle.

tool connections (tool calling, MCP servers)
output validation
retry logic
structured output (JSON schema)

If the first two layers are about designing the input you hand to the model (not just what to instruct, but which documents to pull in and what to leave out), the harness is the code that processes that input reliably in a real system. It's traditional software engineering: validation, retries, exception handling. A familiar analogy is an external API client. It's a lot like putting timeouts, retries, and response validation around a remote service. The difference is that model calls add a new failure class on top of network errors and 5xx responses: semantic failures, where the output is malformed or plausibly wrong.

Model output is probabilistic, so you get format errors and missing pieces. You ask for JSON and it comes back wrapped in a markdown code block, or with a field missing. The harness validates and retries on these failures, and it also manages tool calls and feeds their results back in.

Example. To run the code review in GitHub Actions instead of a chat window, you need code around the model call. What follows is pseudocode for illustration.

# Pseudocode for illustration. In practice, use a Pydantic model or JSON Schema.
REVIEW_SCHEMA = {
    "comments": [{"file": str, "line": int, "severity": str, "message": str}]
}

def review_pr(diff: str, context: str, feedback: list | None = None) -> list[Comment]:
    retry_feedback = None
    for attempt in range(3):
        raw = call_model(
            context=context,
            diff=diff,                      # never mutate the original diff
            feedback=feedback,              # failure records passed in by the outer loop
            retry_feedback=retry_feedback,  # retry reasons travel on a separate channel
            output_schema=REVIEW_SCHEMA,
        )
        try:
            result = validate(raw, REVIEW_SCHEMA)
        except ValidationError as e:
            retry_feedback = f"Schema error in previous response: {e}"
            continue
        # cross-check that each file and line number belongs to an actual changed hunk
        invalid = find_invalid_comments(result.comments, diff)
        if invalid:
            retry_feedback = "Some comments don't match actual diff lines."
            continue
        return result.comments
    raise ReviewFailed("Failed after 3 retries")

The harness does three things here. It requests structured output and validates it against a schema, it retries with the failure reason fed back in, and it cross-checks locations the model may have made up (files or lines that aren't in any changed hunk). That last one matters most. Prompts alone can't fully prevent bad output, so anything you can verify in code, verify in code. Retrying or failing on invalid comments, rather than silently filtering them out, is also a deliberate choice. If you just drop the made-up comments, a response where every comment is invalid becomes an empty list, which reads as "no issues found."

This validation and recovery logic is what turns a model call into a reliable software component. Things that work fine in a demo fail intermittently in production, on parsing or validation, and catching those failures is the harness's job. A production harness also includes logging, cost tracking, and collecting failure cases. If you don't record failures, you don't know what to improve.

By this post's classification, Claude Code itself can be seen as a harness around the model. It provides the execution structure: not just model calls, but tool execution, file editing, and permission checks. If you use Claude Code, you're already using a harness every day.

The difference between context and harness shows up clearly if you compare CLAUDE.md with hooks. Write "run the linter before committing" in CLAUDE.md and it's context. It nudges the model to comply, but nothing guarantees it happens. Configure a PreToolUse command hook that fires before git commit runs, and now the commit can be blocked in code when the lint fails. Same goal, different enforcement depending on which layer it lives in. Things you can leave to the model's judgment go in context; things that must be guaranteed go in the harness.

But if retries are the harness's job, what's different about the next layer, the loop? The unit of retry. The for attempt in range(3) in the code above retries the same model call until it gets output in the right shape. The goal is one valid response. A loop, on the other hand, repeats the entire review-fix-test cycle until it reaches a target state. The harness builds reliable parts; the loop assembles those parts and drives them toward a goal.

4. Loop Engineering

The outermost layer. This is where the system starts running on its own:

a goal and stop conditions
iterating with self-checks and adjustments

Even a system with a solid harness stops after one run, which means a human has to keep issuing the next instruction. A loop sets a goal and stop conditions, like "until all tests pass" or "until lint errors hit zero," and lets the system drive itself.

Example. Let's push the review system one step further: instead of just pointing out problems, it fixes them too, repeating review, fix, and re-verify on its own. Pseudocode again.

MAX_ITERATIONS = 5

def auto_fix_pr(pr):
    feedback = []                                   # loop state that persists across iterations

    # check the baseline first: tests that were already broken go to a human
    baseline = run_tests(pr)
    if not baseline.passed:
        return pr.request_human_review("Tests were failing before auto-fix started")

    for i in range(MAX_ITERATIONS):
        comments = review_pr(pr.diff, pr.context, feedback=feedback)  # reusing layer 3

        if not comments:
            result = run_tests(pr)
            if result.passed:
                # mark the AI review as passed; final approval stays with a human
                return pr.request_human_approval("Passed AI review and tests")
            # no comments but tests fail: skip fixing, go to the next iteration
            feedback.append({"type": "test_failure", "log": result.failure_log})
            continue

        pr, fix_commit = apply_fixes(pr, comments)  # keep the fix commit ID

        result = run_tests(pr)                      # self-check
        if result.passed:
            feedback = []                           # clear resolved failure records
        else:
            pr = revert_commit(pr, fix_commit)      # revert exactly the commit the AI made
            feedback.append({                       # carry the failure log to the next iteration
                "type": "test_failure",
                "log": result.failure_log,
            })

    return pr.request_human_review("Unresolved after 5 iterations")  # stop condition

Everything is in there: a goal (no comments plus passing tests), self-checks (running tests), adjustment (revert on failure and carry the log forward in feedback), and stop conditions (5 iterations max, then escalate to a human). The fact that auto_fix_pr calls review_pr from layer 3 directly is the relationship from the previous section: the loop assembles the parts the harness built.

Failure logs go into feedback outside the loop body, not into a local variable of the current iteration. That's what lets the next model call actually see the earlier failures. And once a fix passes the tests, the accumulated failure records get cleared. There's no reason for the next review to keep referring to errors that were already resolved.

Fix commits are only created when there are comments, and the revert targets the exact commit ID that apply_fixes returned. Reverting "the last commit" can delete the wrong commit if a human pushes while the loop is running.

Checking the baseline tests before entering the loop follows the same logic. To treat a test failure as the result of an AI fix, you first have to know the PR's tests were passing before the auto-fix started. If they were already failing, reverting the last fix commit won't solve anything.

It also matters that meeting the conditions doesn't auto-approve the PR. The AI finding no comments is not a guarantee the code is fine, so final merge approval stays with a human. Permission control spans both the harness and the loop, but it becomes especially important at the loop stage, once the system starts acting repeatedly. In real operations, it's safer to auto-fix only low-risk categories like formatting rather than applying every comment automatically.

Claude Code fixing code, running tests, reading the failures, and fixing again is a good example of a loop.

The heart of it is the stop conditions. Without a max iteration count, a cost ceiling, and a success criterion, a loop either runs away or spins in place. Take MAX_ITERATIONS and the human escalation out of the example above, and you have a system that burns tokens forever on a PR whose tests can never be fixed.

Without a loop, a human has to check the result and issue the next instruction on every iteration. Iteration with self-checks is a core ingredient of agent systems. But an actual agent combines this with tool use, state management, and permission control, so a loop by itself is not the whole of an agent.

Summary

Layer	What it does	In the code review scenario	Without it
1. Prompt	The request you type	"What to look at, what to ignore"	Nothing starts
2. Context	Background the model sees	Team conventions, related code, past reviews	It guesses
3. Harness	Validation, retries, tool wiring	Schema validation, line-number cross-checks	It wobbles
4. Loop	Goals, stop conditions, iteration	Review-fix-test cycle, human keeps final approval	It stalls

A great prompt without context guesses. Great context without a harness wobbles. A harness without a loop stalls. And for repetitive work without a loop, you become the bottleneck.

If all you've been doing is polishing prompts, you've been working on just the innermost layer. When the results still disappoint, the next improvement may be further out.

Originally published at jamongx.com.

Claude Code Skills Guide: How to Automate Your Development Workflow

jamongx — Mon, 13 Jul 2026 01:14:05 +0000

Claude Code is a terminal-based coding agent that can automate the repetitive parts of your development workflow, not just generate code.

This article isn't about installation or basic usage. It's written for developers already using Claude Code who want to learn how to design Skills that deliver meaningful automation and consistency in real-world projects.

Among Claude Code's features, Skills are the main way to define how Claude should handle repeatable tasks and follow your project's engineering conventions. In this article, we'll look at how they keep code quality consistent across a team.

Updated July 2026 — The January version of this guide described Skills as single .md files in .claude/commands/. Skills have since become directory-based (.claude/skills/<name>/SKILL.md), adopted a formal frontmatter specification, and become an open standard at agentskills.io. This revision reflects the current format. The examples come from skills I actually use in real projects.

1. What Are Skills?

In Claude Code, a Skill is a directory containing a SKILL.md file with the instructions, resources, and execution steps Claude follows when the skill is invoked. For personal and project skills, the directory name becomes the command name: .claude/skills/code-review/SKILL.md gives you /code-review. (Plugin skills are namespaced by the plugin name: /my-plugin:review.)

Rules are your 'Policy Documents'
Skills are your 'Standard Operating Procedures'

The important distinction is this: a Skill is not an independent agent. It packages instructions, resources, and tool permissions—Claude, or you, decides when to invoke it, unless the frontmatter restricts invocation.

If you remember "custom slash commands" (.claude/commands/*.md): they've been merged into Skills. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and old command files keep working. Skills are the recommended format—they add supporting files, invocation control, and a richer frontmatter. If both define the same name, the skill wins.

2. Skill File Structure and Location

Skills can be managed per-project or globally across your machine:

Scope	Location	Applies to
Personal	`~/.claude/skills/<name>/SKILL.md`	All your projects
Project	`.claude/skills/<name>/SKILL.md`	This project only (shared via Git)
Plugin	`<plugin>/skills/<name>/SKILL.md`	Wherever the plugin is enabled

The file must be named exactly SKILL.md, and a skill is a directory, not a single file. That directory can carry supporting material that loads only when needed:

code-review/
├── SKILL.md          # required: frontmatter + instructions
├── references/       # detailed docs, loaded on demand
├── scripts/          # executable helpers (run, not loaded)
└── assets/           # templates, static resources

For me, this is the most useful improvement over the old single-file format. Keep SKILL.md under ~500 lines and push heavy reference material into references/—the body stays in context for the whole session once loaded, so every line has a recurring token cost.

The Key: YAML Frontmatter

---
name: code-review
description: Review code against .claude/rules/ for architecture and convention violations.
argument-hint: "[path] [--staged|--branch] [--fix]"
allowed-tools: Read Glob Grep Bash(git *)
---

☝️ The description field is still critical. Claude normally sees the names and descriptions of available Skills and uses that metadata to decide which one is relevant. If you say "review my code," that request gets matched against skill descriptions—so yours must contain clear, searchable keywords.

One distinction worth knowing before the table: the Agent Skills standard defines the portable core fields (name, description, license, compatibility, metadata, allowed-tools). The rest below—argument-hint, disable-model-invocation, user-invocable, context—are Claude Code extensions. The table covers the fields used in this guide, not every option Claude Code supports (there are also when_to_use, model, paths, hooks, and more):

Field	What it does
`name`	Display name (defaults to the directory name)
`description`	Auto-invocation trigger. Keep it ≤1,024 chars for cross-tool compatibility
`argument-hint`	Autocomplete hint shown after `/name`
`allowed-tools`	Tools Claude may use without permission prompts while the skill runs (space-separated per the standard; Claude Code also accepts commas)
`disable-model-invocation`	`true` = only you can trigger it; Claude never auto-invokes
`user-invocable`	`false` = hidden from the `/` menu; Claude-only background knowledge
`context: fork`	Run the skill in an isolated subagent context

Two of these encode a design decision the old format couldn't express: who is allowed to pull the trigger. For side-effect workflows—deploying, committing, sending messages—set disable-model-invocation: true so Claude can't decide on its own that now is a good time to deploy. For pure background knowledge, set user-invocable: false so it stays out of your command menu.

3. Real Example: `/code-review` Skill

The architecture-review skill from the January version of this post is still the one I use every day—it has just grown up. Here's the frontmatter of my current production /code-review skill:

---
name: code-review
description: Review code against .claude/rules/ for architecture and convention
  violations. Supports --staged, --head, --last, --today, --branch scope options.
  Add --fix to auto-correct.
argument-hint: "[path] [--staged|--head|--last|--today|--branch] [--fix]"
allowed-tools: Read, Glob, Grep, Edit, Bash(git *), Bash(find *)
---

The current version relies on two features that didn't exist in January:

1. Arguments. $ARGUMENTS in the skill body is substituted with whatever you type after the command, so one skill covers many scopes:

Invocation	Review scope
`/code-review`	Files changed in the last 5 commits
`/code-review src/user/`	A specific directory
`/code-review --staged`	Final check right before committing
`/code-review --branch`	Current branch vs main, before opening a PR
`/code-review --staged --fix`	Auto-fix what it finds

2. Dynamic context injection. A !`command` placeholder runs before Claude sees the skill and gets replaced with its output. My skill uses it to enumerate the rule files and changed files up front:

- Project rules: !`find .claude/rules -name "*.md" | sort`
- Staged files: !`git diff --name-only --cached`

The Claude Code client runs these commands during preprocessing; the model receives only the expanded results as part of the skill instructions. That removes an entire class of "the model forgot to check X first" failures.

📎 Full working example: code-review SKILL.md — save it as .claude/skills/code-review/SKILL.md in your project. The directory name is what creates the /code-review command.

Claude Code already ships a bundled /code-review skill. Adding your own code-review skill at the personal or project level overrides the bundled version—which is exactly what I want here: a review driven by my rule files, not a generic one.

Why This Skill Is Powerful

Rule-driven checklists — The skill loads .claude/rules/ dynamically instead of hardcoding policies, so the same skill works in every project and stays aligned with the current rule files.
Severity Level definitions — CRITICAL/WARNING/SUGGESTION priorities prevent getting lost in minor issues.
Explicit execution process — A five-step procedure makes the review process more consistent.

4. Example Output

Running /code-review in the terminal produces results like this:

> /code-review src/user/api/user_router.py

🔍 Reviewing: src/user/api/user_router.py

## Architecture Violations Found

### 🚨 CRITICAL (2)

**Line 45**: Direct Repository import detected
  - Found: `from src.user.repositories.user_repository import UserRepository`
  - Fix: Remove this import. Use Service layer instead.

**Line 78**: Business logic in API layer
  - Found: `if user.age >= 18 and user.verified:`
  - Fix: Move this validation to UserService.validate_user_eligibility()

### ⚠️ WARNING (1)

**Line 23**: Service manually instantiated
  - Found: `service = UserService()`
  - Fix: Use `service: UserService = Depends(get_user_service)`

### 💡 SUGGESTION (1)

**Line 12**: Consider adding return type hint
  - Current: `async def get_user(user_id: int):`
  - Suggested: `async def get_user(user_id: int) -> StandardResponse[UserResponse]:`

---
Summary: 2 critical, 1 warning, 1 suggestion
Run `/code-review --fix` to auto-fix applicable issues.

One command produces a repeatable first-pass architecture review based on your project's documented rules. It doesn't replace human review—but it catches routine violations before a pull request ever reaches another developer.

Security Note: Review Skills Before Trusting Them

The same two features that make skills powerful make them worth auditing. Skills are executable workflow definitions, not passive documentation:

allowed-tools pre-approves tool usage for the duration of the skill—no permission prompts.
Dynamic context expressions like !`command` run during preprocessing, before the rendered skill content ever reaches the model.
A skill checked into an unfamiliar repository deserves a read before you accept workspace trust. (You can disable shell preprocessing entirely with the disableSkillShellExecution setting.)
Keep permissions narrow: Bash(git *) beats Bash(*), and list only the tools the procedure actually needs.

5. Where Skills Provide the Most Value

① Consistent Code Quality

Human reviewers vary by mood and energy. A well-defined Skill applies the same checklist every time, reducing variation and making common omissions less likely.

② Encapsulating Complex Workflows

Tasks that touch multiple files (adding a new API endpoint requires Router, Service, Schema, and Test files) can be bundled into a single Skill, reducing the chance of missing a step.

③ Knowledge as an Asset

Embed your design philosophy into Skill files and share via Git. Junior developers can generate code that is consistently aligned with documented senior guidelines. And because Skills follow an open standard, the SOPs you encode aren't locked into one tool.

6. Practical Patterns

These are skills currently in my ~/.claude/skills/ and project .claude/skills/ directories—not hypotheticals:

Skill Command	What It Does
/code-review	Check architecture violations against `.claude/rules/` with severity levels and `--fix`
/commit-push	Stage, generate a conventional commit message, confirm, push
/create-post	Scaffold a new blog post following every content convention (slug rules, image folders, frontmatter schema)
/feature-image	Crop and convert cover images to 16:9 WebP under a size budget
/review-skill	The meta one: audit `SKILL.md` files against the open standard, with `--fix`

Notice the pattern in the last row—once your process knowledge lives in files, you can write skills that maintain other skills.

7. Key Tips for Designing Skills

Craft your description carefully — It's the primary signal Claude uses to decide when to load a Skill automatically. Describe both what the skill does and when to use it: "Review code for Clean Architecture compliance" beats "Code review."
Link to Rules — Instead of duplicating policies inside the skill, load them: .claude/rules/ is the single source and the skill is the procedure that applies it.
Make checklists explicit — "Review this code" produces inconsistent results. "Check these 5 things" delivers reliability.
Define Severity Levels — Not all issues are equal. Include priority criteria in your Skill.
Add verification steps — Always end with "verify the modified code builds" or "run lint" as a final check.
Keep SKILL.md lean — Under ~500 lines. Move deep reference material to references/ files that load on demand; the skill body occupies context for the whole session.
Control the trigger — Side-effect workflows (deploy, commit, publish) get disable-model-invocation: true. Guardrails belong in frontmatter, not in hope.
Combine with MCP — If you have MCP servers connected to external tools (GitHub, databases), you can write instructions like "query the DB schema before writing code" for smarter automation.

Conclusion

Claude Code Skills turn repeated instructions into reusable, version-controlled workflows.

Their quality depends less on clever prompting than on how clearly you've defined the process Claude should follow.

If your team repeatedly explains the same conventions during code reviews, those conventions are good candidates for a Skill. Start with one narrow workflow, test it against real tasks, and refine it as your process changes.

In the next article, we'll explore Custom Agents—how to build AI that autonomously decides when to use which Skill.

Series:

Enforcing Team Architecture with .claude/rules in Claude Code (FastAPI Practical Guide) — Teaching AI your policies
Skills Guide — Teaching AI your procedures (this article)
Claude Code Agents Guide: How Skills Power Your Subagents — Teaching AI when to act