Methods & Practice
A structured framework for working with Claude Code across real software projects. It defines how the assistant behaves, what roles it takes on, what context it carries between sessions, and what decisions require human approval before proceeding.
This is not a plugin or a product. It is the layer that runs beneath the visible work — coordinating rules, memory, roles, and workflow across every project, consistently, without requiring the human to hold all of that structure in mind.
The name is deliberate. Like an operating system running beneath an application, AI Development OS runs beneath the development process itself — providing memory, structure, rules, and coordination across projects.
This framework is built on one idea: good practice should not depend on memory alone.
What it is
AI Development OS is a personal framework for AI-assisted software development. It combines persistent memory, role-based collaboration, lightweight Agile planning, approval gates, and project-specific context into a repeatable operating model.
Its purpose is simple: reduce context loss, improve consistency, and make AI-assisted development feel more like engineering.
Why it exists
AI Development OS started from a practical problem: every session with Claude Code began from a blank slate.
The project's stack had to be explained again. The current phase had to be described. Previous decisions had to be recalled or rediscovered. Safety rules had to be repeated. Git discipline depended on reminders. There was no reliable way to say: here is the project context, pick up where we left off.
Every time a session ended, the context ended with it. The next session did not know what the last one had decided, what constraints existed, or where the work had stopped.
The solution was not a better AI. The solution was a layer that carried the structure between sessions.
The issue was not capability. The tools were capable. The issue was structure. Without it, each session required rebuilding the working context from scratch. Work could not compound. Discipline could not persist. The human had to carry all of it.
Origin
At the time, I was trying to improve how I worked with AI across multiple projects, not create a framework. The first response was practical. I created a global rules folder at ~/Projects/_AI_RULES — one place where collaboration behaviour could be defined once and applied across every project, without rewriting the same instructions from scratch every session.
The initial framework included a master autonomous development framework, safety rules, development workflow, and early memory structure, with planned files for security, deployment, coding standards, and memory. At that stage it was personal, practical, and opinionated — built to reflect how I wanted to work: step by step, with Git discipline, with clear boundaries, and with human approval before anything irreversible.
While I was developing the framework, a friend and IT professional, Bogdan, mentioned the BMAD framework and suggested I take a look at it. Some of the ideas were close to problems I was already trying to solve: structured roles, clear handoffs, and disciplined collaboration between specialised sessions. I explored it and borrowed ideas that made sense for my own workflow.
Around the same period, I also added a lightweight Agile layer to bring more structure around planning, review, and decision-making: a backlog, epics and stories, acceptance criteria, decision logs, retrospectives, and explicit human approval checkpoints at every significant decision point.
The result became AI Development OS — a personalised operating model shaped by my own projects, my working style, lessons learned while building LegionTrap, and useful ideas gathered from different sources along the way.
The operating model
AI Development OS operates in six layers. Each layer addresses a different part of the problem: what the AI knows, how it behaves, what roles it holds, what it remembers between sessions, how the work is structured, and when the human must approve before anything proceeds.
A shared rules layer defines safety, coding standards, deployment authority, security requirements, and collaboration rules across every project. These rules load once and apply everywhere — behaviour is consistent because the rules are consistent.
Each project connects to the framework through a CLAUDE.md file and project-specific memory files. The project's context, status, decisions, and backlog are always available at the start of a session.
Eight specialised roles separate analysis, planning, architecture, implementation, testing, security review, and DevOps review. Roles do not blur. An Analyst does not write code. A Developer does not plan architecture.
Project status, summary, backlog, decision log, and retrospective files preserve context between sessions. The next session picks up from a known state rather than a blank one.
Work is organised into epics, stories, and acceptance criteria. Each story has a done-when condition defined before work begins. Retrospectives run at the end of each phase. The planning structure sits above individual sessions.
Before commits, deployments, migrations, or risky changes, the AI prepares the work and the human approves the action. Approval is not optional and cannot be delegated back to the AI.
Components
AI Development OS is made up of four interlocking components — from global rules that apply everywhere to per-project memory that preserves what has been done.
The foundation of AI Development OS. A set of shared rule files in
~/Projects/_AI_RULES that define collaboration behaviour, safety
constraints, coding standards, deployment authority, and security
requirements. Every project loads these at the start of each session —
behaviour is consistent because the rules are consistent.
AUTONOMOUS_DEV_FRAMEWORK.md · AI_AGENT_RULES.md · GLOBAL_CODING_STANDARDS.md · SECURITY_RULES.md · DEPLOYMENT_RULES.md · MEMORY_SYSTEM.md
Before a project is onboarded into AI Development OS, templates define what the project's CLAUDE.md and status files should contain. Templates ensure every project connects to the framework in the same way — the same structure, the same memory format, the same checkpoints — regardless of the project's technology or scope.
PROJECT_CLAUDE_TEMPLATE.md · PROJECT_ONBOARDING_TEMPLATE.md · PROJECT_STATUS_TEMPLATE.md
Project context lives in files, not only in conversation history. Each project carries a persistent set of memory files that preserve its current status, decisions made, work in progress, and what the next session should pick up. When a session begins, the relevant files are loaded and context is restored without reconstruction.
PROJECT_STATUS.md · PROJECT_SUMMARY.md · PROJECT_BACKLOG.md · DECISION_LOG.md · RETROSPECTIVE.md
A planning structure that sits above individual sessions. Work is organised into epics and stories. Each story has acceptance criteria and a done-when condition. Decisions are logged. Retrospectives are written at the end of each phase. Human approval checkpoints are explicit — they are not optional steps that can be skipped under time pressure.
epics · stories · acceptance criteria · backlog · decision log · retrospectives · done-when conditions · human approval checkpoints
Role definitions
AI Development OS currently defines eight specialised roles. Each session activates one role. The role determines what the assistant is optimising for, what it produces, and what it must not do. Roles do not blur — an Analyst does not write code, a Developer does not plan architecture, a DevOps Reviewer does not deploy without human approval.
Reviews overall project goals, identifies risks and blockers, and advises on prioritisation and scope. Activates at project kickoff, phase transitions, and when direction is unclear. Produces recommendations, risk assessments, and priority guidance.
Must not: make implementation decisions or write code
Inspects the repository, reads existing code, documents what exists, and identifies gaps between current state and intended direction. Activates before any planned change, during onboarding, and when context is unclear. Produces inspection reports, codebase summaries, and gap analysis.
Must not: modify code or make recommendations beyond what the evidence supports
Translates project goals into epics, stories, and acceptance criteria. Maintains the backlog and ensures work is scoped before it begins. Activates during phase planning, story definition, and acceptance criteria review. Produces stories, backlog updates, and done-when conditions.
Must not: make technical implementation decisions or approve changes
Defines data structures, component boundaries, interface contracts, and the rationale behind each. Produces plans and specifications the Developer will execute. Activates before implementation begins and when design decisions are required.
Must not: write implementation code or allow implementation difficulty to drive design decisions
Produces code that satisfies a defined specification. Works within decisions already made. Flags gaps rather than resolving them autonomously. Activates after a specification exists and has been approved. Produces code, tests, and pull request branches.
Must not: make architectural decisions or modify scope during implementation
Defines the test strategy, writes test cases, and verifies that implementation satisfies the acceptance criteria defined before work began. Activates after implementation and before merge approval. Produces test plans, test cases, and pass/fail findings.
Must not: modify implementation code or approve merges unilaterally
Reviews code changes for security vulnerabilities, unsafe patterns, exposed credentials, and deviations from the defined security rules. Activates before any merge of security-relevant code. Produces security findings, risk assessments, and remediation recommendations.
Must not: apply fixes directly or approve changes without human review
Reviews deployment-related changes against the defined deployment rules. Validates that infrastructure changes are safe and reversible where possible. Activates before any deployment, migration, or infrastructure change. Produces deployment readiness assessments and approval checklists.
Must not: execute deployments or approve changes without explicit human sign-off
First validation project
AI Development OS was first validated on LegionTrap TI, an active project at ~/Projects/gitrepo/legiontrap-ti. LegionTrap provided the right conditions for an initial test: an existing, non-trivial codebase with real history, real decisions, and real complexity.
The validation scope was deliberate and bounded. The goal was not to run a full feature development cycle — it was to confirm that AI Development OS onboarding, memory, and workflow components functioned correctly on a real repository before expanding use.
What was tested: project onboarding using templates, memory file creation, Analyst inspection tasks, a controlled Developer cleanup task, a second narrow Analyst task, an approved cleanup step, full PR workflow including docs/ and chore/ branches, commits, pull requests, merges into main, and branch deletion. Human approval was required at every stage.
AI Development OS is currently validated for low-risk onboarding, repository inspection, controlled cleanup tasks, memory creation, and the GitHub PR workflow. It is not yet fully validated for complex feature development, migrations, production deployment, or the Security Reviewer and DevOps Reviewer workflows. Those validations are the next step.
Observed outcomes
The practical result is simple: less time rebuilding context, fewer forgotten constraints, and a more consistent development process across long-running projects.
Design principles
Rules that must be restated in every prompt are fragile. A rule that lives in a file and loads automatically is reliable. AI Development OS replaces session-by-session reminders with consistent, persistent structure.
Project context should live in files, not only in conversation history. Reconstructing context from memory introduces error. Preserving it in structured files makes every session start from a known state.
Different kinds of work require different responsibilities. Analysis, design, implementation, and review are different activities. Mixing them in a single session produces inconsistent output. Separating them produces cleaner work.
The AI prepares the work. The human approves the action. Before anything irreversible — a commit, a deployment, a migration — the assistant stops and waits. Autonomy is bounded at every significant decision point.
Use enough structure to know what is being built, why, and when it is done — without adding unnecessary process. Epics, stories, acceptance criteria, and retrospectives serve the work. They do not become the work.
Architecture overview
AI Development OS currently consists of six interconnected layers working together as a single operating model:
Each component addresses a different failure mode. Together they form a system where the human stays in control and the AI stays in context.
Current state
Working personal framework · actively used · active refinement · first validation complete
Global rule system, project CLAUDE.md template, project onboarding template, project status template, per-project memory files, agent role system, lightweight Agile layer, human approval checkpoints, Git safety rules, and deployment safety rules are all operational. The full eight-role pipeline has not yet been run end-to-end on a real feature.
Validated so far
Not yet fully validated
Validate the full role pipeline — story definition through architecture, implementation, QA, security review, and DevOps review on a real feature branch
Long-term direction
This is not a finished method. It is a working practice. The direction it takes is determined by what the work reveals — not by what was planned at the outset.
Near term: full role pipeline validation. The full eight-role pipeline has not been run end-to-end on a real feature. The next step is doing exactly that — taking a real feature from story definition through architecture, implementation, QA, security review, and DevOps review, with human approval at each handoff.
Medium term: multi-project use. LegionTrap is the first project in AI Development OS. Applying AI Development OS to a second project will reveal which parts are genuinely portable and which parts need adjustment for different technologies, scopes, and working styles.
Long term: engineering discipline. The long-term goal is not to create a shiny AI product. The goal is to make AI-assisted development feel more like engineering: structured, traceable, reviewable, and improvable — not a series of capable but disconnected conversations.
The objective is not to automate software development. The objective is to make software development more consistent.
This is not a finished method.
It is a working practice — documented well enough to repeat, and used long enough to improve.
The framework exists so that discipline becomes part of the system rather than something the human must remember to recreate every session.
AI Development OS is not intended to replace engineering discipline. It exists to make engineering discipline easier to apply consistently.
The goal, held consistently: AI-assisted development that feels like engineering — structured, traceable, and improvable — rather than a series of capable but disconnected conversations.