Since the early days of GenAI, when ChatGPT launched in late 2022, we began using prompt engineering to direct chatbots (and later LLMs) with human language instructions to provide us answers to questions or take actions (in a high-level…)
In 2025, companies such as OpenAI and Anthropic began releasing a new agentic concept called “AI Agent”, an autonomous system that uses an AI model as its "brain" to perceive an environment, make independent decisions, and execute multi-step tasks using digital tools. Unlike passive chatbots that just answer questions, an agent can plan its own workflow, run commands, and browse the web to achieve a specific goal without constant human supervision.
In this blog post, I will explain the concept of Context-as-Code and share some coding examples.
Introducing Context-as-Code
Traditional prompting is a one-way street. You type out your instructions, send them off, and that text never changes.
AI agents operate completely differently. Because they work on their own, every action they take creates a mountain of new data. Every time an agent opens a file, checks an error, or runs a tool, it adds more information to the pile, which quickly overwhelms a standard chat screen.
Context-as-Code treats the agent like a stateless compute engine. Instead of a massive text prompt, we use version-controlled files (CLAUDE.md, AGENTS.md) to establish structural boundaries, separating the permanent project rules from the temporary, dynamic session memory.
Context-as-Code transforms loose AI prompts into version-controlled engineering assets by using structured Markdown files to establish permanent, auditable boundaries directly within a project repository.
The Discovery Stage (Onboarding the Agent)
Before an agent writes a single line of code, it must parse the overall project layout. These files act as the "map" for an incoming AI.
llms.txt
Serves as a lightweight text directory mapped out in Markdown format. Placed at the root of a project or website, it acts exactly like a robots.txt for AI. It points roaming models and agents to the exact location of your documentation and architecture maps so they don't get lost crawling messy HTML or redundant folders.
Reference:
ARCHITECTURE.md
Outlines the systemic design rules, folder hierarchies, and database schemas. Agents read this during the planning phase of a task to ensure a newly generated feature doesn't conflict with core infrastructure boundaries.
Reference:
The Configuration Stage (Setting Workspace Rules)
Once the agent understands the codebase, it requires a strict behavioral contract. These files dictate the workspace boundaries (Always Do / Never Do) that govern every automated action.
AGENTS.md
Establishes cross-tool workspace guardrails and strict coding boundaries. It tells any agent entering the repo how to format code, run local builds, and what architectural limits to never cross. This file is fully supported by OpenAI and Cursor.
References:
- AGENTS.md
- A stale AGENTS.md is worse than no AGENTS.md
- Agent Skills Explained: From Basics to Advanced!
CLAUDE.md
This file serves as the dedicated, platform-specific behavioral contract for Anthropic's toolchain. It establishes an immediate project context by outlining exact test suite execution commands and lint rules, which prevents the agent from getting confused mid-session.
Natively executed by Anthropic's Claude Code CLI and fully integrated into Microsoft Visual Studio Code (VS Code), which automatically detects and honors CLAUDE.md memory files and workflows.
References:
The Runtime & Execution Stage (Performing the Task)
When a user tells an agent to run a specific procedural task (e.g., "Review this PR for security leaks" or "Deploy this service"), the agent switches from broad guardrails to highly specific, dynamic execution instructions.
SKILL.md
Defines a modular, task-specific capability or playbook. It utilizes YAML frontmatter metadata so an agent can quickly scan what the skill does, only loading the heavy step-by-step instructions when a user explicitly requests that specific workflow.
This file is supported by Claude Code, Cursor Editor, GitHub Copilot Agent Mode, Codex CLI, and Gemini CLI.
References:
prompts.md
Houses version-controlled, multi-shot system prompts or reusable engineering templates. Instead of hardcoding prompts into application backends, these files turn complex agent prompts into modular workspace assets.
Widely used in prompt registries across custom enterprise stacks (AWS Bedrock, OpenAI Assistants API) and natively inside VS Code's extension prompt libraries.
Reference:
Below is a visualization of the AI agentic workspace lifecycle:
Summary
The shift from manual prompt engineering to autonomous AI agents requires a new approach called Context-as-Code. By replacing static prompts with version-controlled Markdown files inside a repository, developers can establish clear architectural maps, behavioral guardrails, and execution playbooks that guide an agent safely through its onboarding, configuration, and runtime lifecycle stages.
Using structured files like CLAUDE.md, AGENTS.md, and SKILL.md turns vague instructions into auditable engineering assets that keep an agent's memory clean and predictable. Because autonomous agents can independently alter code and run terminal commands, teams should actively expand their knowledge and gain hands-on experience in development settings before deploying these agentic workflows into production.
Disclaimer: AI tools were used to research and edit this article. Graphics are created using AI.
About the Author
Eyal Estrin is a cloud and information security architect and AWS Community Builder, with more than 25 years in the industry. He is the author of Cloud Security Handbook and Security for Cloud Native Applications.
Top comments (0)