Agent Context Management
Relevant source files
The following files were used as context for generating this wiki page:Agent Context Management is a system within the Spec-Driven Development (SDD) workflow designed to provide AI coding agents with up-to-date, relevant information about the project. It maintains dedicated context files for different agents (e.g., Claude Code, Gemini CLI, GitHub Copilot), which are automatically and incrementally updated as new features are planned. This ensures the AI agent has a consistent understanding of the project's technology stack, structure, and recent changes, leading to higher-quality, more consistent generated outputs.
The process is initiated when a new project is created using the specify init command and is subsequently triggered each time the /plan command is executed to create an implementation plan for a new feature. This keeps the agent's knowledge synchronized with the project's evolution.
Sources: spec-driven.md, README.md, templates/plan-template.md:143-150
Core Components
The system is composed of several key parts that work together to manage the agent's context.
| Component | Description | Relevant Files |
|---|---|---|
| Agent Context Files | Markdown files (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md) that store project-specific guidelines for the AI agent. | templates/agent-file-template.md, scripts/update-agent-context.sh:13-15 |
specify CLI | The command-line tool used to bootstrap a new project. It prompts the user to select an AI agent and creates the corresponding initial context file. | src/specify_cli/__init__.py |
update-agent-context.sh | A shell script responsible for parsing new feature plans and incrementally updating the agent context files with new information. | scripts/update-agent-context.sh |
/plan Command | The command that triggers the context update process as part of its execution flow when generating a new feature plan. | templates/plan-template.md:143-150, templates/commands/plan.md |
Sources: src/specify_cli/init.py, scripts/update-agent-context.sh, templates/plan-template.md
Agent Context File Structure
The agent context files are generated from a standard template, agent-file-template.md. This template defines a structured format for conveying project information to the AI.
# [PROJECT NAME] Development Guidelines
Auto-generated from all feature plans. Last updated: [DATE]
## Active Technologies
[EXTRACTED FROM ALL PLAN.MD FILES]
## Project Structure
[ACTUAL STRUCTURE FROM PLANS]
## Commands
[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
## Code Style
[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
## Recent Changes
[LAST 3 FEATURES AND WHAT THEY ADDED]
<!-- MANUAL ADDITIONS START -->
<!-- MANUAL ADDITIONS END -->
Source: templates/agent-file-template.md
Sections Explained
| Section | Purpose |
|---|---|
| Active Technologies | Lists the languages, frameworks, and databases currently in use, extracted from all plan.md files. |
| Project Structure | Provides a high-level view of the repository's directory structure. |
| Commands | Contains relevant commands for testing and linting based on the active technologies. |
| Code Style | Specifies coding conventions for the languages in use. |
| Recent Changes | A rolling list of the last three features added to the project, providing context on recent evolution. |
| Manual Additions | A preserved block where developers can add custom instructions or guidelines that will not be overwritten by the update script. |
Sources: templates/agent-file-template.md, scripts/update-agent-context.sh:101-104
Workflow and Data Flow
The context management lifecycle has two main phases: initial creation during project setup and incremental updates during feature development.
Project Initialization
When a developer runs specify init, the CLI tool guides them through selecting an AI agent and downloads the appropriate template to create the project structure, including the initial agent-specific context file.
The following diagram illustrates the project initialization flow.
Source: src/specify_cli/init.py:433-524
Incremental Update Process
The context file is updated whenever the /plan command is successfully executed. The update-agent-context.sh script is called, which reads the newly created plan.md for the feature, extracts key technical details, and merges them into the existing agent context file.
This diagram shows the data flow for an incremental update.
update-agent-context.sh Technical Details
The update script is the core of the incremental update mechanism. It uses a combination of shell commands and an embedded Python script to perform its tasks.
Information Extraction from plan.md
The script uses grep and sed to parse key technical details from the plan.md file of the current feature branch.
| Extracted Field | plan.md Source Line | grep Pattern |
|---|---|---|
NEW_LANG | **Language/Version**: | ^**Language/Version**: |
NEW_FRAMEWORK | **Primary Dependencies**: | ^**Primary Dependencies**: |
NEW_TESTING | **Testing**: | ^**Testing**: |
NEW_DB | **Storage**: | ^**Storage**: |
NEW_PROJECT_TYPE | **Project Type**: | ^**Project Type**: |
Source: scripts/update-agent-context.sh:24-29
Update Logic
The update_agent_file function contains the main logic for updating a context file. If the file doesn't exist, it's created from the agent-file-template.md. If it does exist, an embedded Python script is executed to perform a more sophisticated merge.
Key logic within the Python script includes:
- Preserving Manual Additions: It finds and saves the content between
<!-- MANUAL ADDITIONS START -->and<!-- MANUAL ADDITIONS END -->markers, and re-appends it after the update. - Updating Active Technologies: It checks if the new language or database from
plan.mdis already listed. If not, it appends the new technology along with the current feature branch name as context. - Updating Recent Changes: It prepends the new feature to the "Recent Changes" list and truncates the list to keep only the last three entries.
- Updating Date: It updates the
Last updated:timestamp to the current date.
Sources: scripts/update-agent-context.sh:32-200, templates/agent-file-template.md
Supported AI Agents
The spec-kit is designed to work with multiple AI coding agents. The specify init command allows the user to select their preferred agent, which determines which context file is created and maintained.
| Agent Name | specify init Flag | Context File |
|---|---|---|
| GitHub Copilot | copilot | .github/copilot-instructions.md |
| Claude Code | claude | CLAUDE.md |
| Gemini CLI | gemini | GEMINI.md |
Sources: src/specify_cli/init.py:41-45, 584-593, scripts/update-agent-context.sh:13-15
Conclusion
The Agent Context Management system is a critical automation feature in the Spec-Driven Development workflow. By maintaining a concise, up-to-date summary of the project's technical landscape directly within the agent's context, it ensures that AI-generated specifications, plans, and code are more accurate and consistent with the project's evolving architecture. This automated, incremental process reduces manual effort and improves the synergy between the developer and the AI agent.
Sources: spec-driven.md, README.md