Structuring Repos to Make Claude a 'Senior Engineer'
A new workflow is emerging for turning LLMs into effective team members by structuring code repositories for them. The method involves creating a `CLAUDE.md` file for repo memory, a `.claude/skills/` directory for reusable workflows, and hooks for guardrails, effectively giving the AI persistent context and skills.
This repository structuring method is part of a broader movement towards "context engineering," which focuses on making codebases self-descriptive for AI agents. The core problem is that AI assistants lack the rich mental context of a human developer, including domain knowledge, architectural nuances, and unwritten coding conventions. This "context blindness" is a significant hurdle, with 65% of developers reporting missing context during refactoring tasks alone. The `CLAUDE.md` file acts as a persistent, high-level memory that is automatically loaded in every session, outlining architecture, common patterns, and project constraints. This is distinct from `.claude/skills/`, which are on-demand, task-specific instructions loaded only when a relevant task is initiated, saving context window space. For example, a `git-commit` skill would only be loaded when the AI is asked to create a commit. This tiered approach of providing context is a key principle called "progressive disclosure." A root `CLAUDE.md` provides universal rules, skills in `.claude/skills/` offer specialized playbooks, and deeper reference materials can be stored in `docs/agent-guides/` that skills can point to. This prevents overloading the AI with irrelevant information for a given task. This workflow treats the AI less like an autocomplete tool and more like a team member that can be managed and taught. By externalizing knowledge into the repository itself, teams can ensure consistent behavior and quality from the AI across different sessions and even different users. The approach aims to shift the engineer's role from writing code to orchestrating and reviewing AI-generated work. The concept is similar to other attempts to standardize AI instructions in repositories, such as the proposed `AGENTS.md` specification. The overall goal is to move beyond single, isolated prompts and build systems around the AI that provide durable, structured context, which is crucial for tackling complex, multi-step software engineering tasks.
