Agentic Software Development Template

This repository contains templates for an Agentic Workflow where an AI Agent (Claude, Gemini, etc.) acts as an intelligent orchestrator alongside a human developer.

📖 This template follows the principles from Writing a good CLAUDE.md by HumanLayer, including Progressive Disclosure for keeping agent instructions concise and relevant.

📂 Contents

File/Folder	Purpose	Updates
.agent/AGENTS.md	Core AI instructions (~70 lines)	Static
.agent/SYSTEM.md	Project context, architecture, tech stack	Dynamic
.agent/docs/	Reference docs (Progressive Disclosure)	As needed
.agent/tasks/task_template.md	Template for task.md files	Static
.agent/archive/task_history.md	Log of completed tasks	Per task

🚀 How to Use

1. Copy Files: Copy .agent/ folder into your project's root
2. Initialize SYSTEM.md: Fill in project overview and tech stack
3. Start Coding:
   • Create a branch from dev
   • Ask the AI to "Start a new task based on task_template.md"
   • AI reads AGENTS.md for instructions and SYSTEM.md for context

🤖 The 3-Layer Architecture

Layer	Location	Purpose
Instructions	AGENTS.md, task.md	Define goals
Orchestration	AI Agent	Make decisions
Execution	Source code	Deterministic output

📚 Progressive Disclosure

Instead of one massive instruction file, the AI reads detailed guides only when relevant:

File	Topic
docs/task-workflow.md	Issue → Task → Code → Archive
docs/git-branching.md	Branching model and git flow
docs/decision-making.md	When to ask vs. decide
docs/breaking-changes.md	Protocol for breaking changes
docs/environment-setup.md	.env and secrets management
docs/project-initialization.md	First-time project setup
docs/error-handling.md	Self-annealing error loop
docs/assumptions.md	Documenting assumptions
docs/testing-guidelines.md	Unit testing best practices
docs/logging-monitoring.md	Logging and monitoring standards
docs/code-review.md	Commits, PRs, and code review
docs/dependencies.md	Managing project dependencies

🔄 Workflow

Issue → Branch → Context Analysis → task.md → Approval → Execute → Archive

1. Context Analysis: AI reads SYSTEM.md, AGENTS.md, task_history.md
2. Task Creation: AI creates task.md from template
3. Execution: AI writes code, writes tests, runs tests
4. Self-Annealing: AI fixes errors based on test output
5. Completion: AI updates docs and archives task

📖 Further Reading

• Writing a good CLAUDE.md - Best practices for agent instructions
• HumanLayer Blog - More on agentic workflows