Optimizing Codebases for Agentic Workflows

To effectively leverage AI agents on existing (Brownfield) projects, developers must shift from writing code for humans to writing code that agents can navigate efficiently.

• Contextual Documentation: Implement context.md files in every directory. These files should summarize the directory's purpose and list the files contained within, allowing agents to understand the codebase structure without reading every file, which saves context window space and improves performance.
• Architectural Flattening: Move toward horizontal, flatter architectures. This structure allows agents to manage state more effectively and makes it easier for them to refactor code by breaking large files into smaller, modular functions.
• Testing as a Foundation: Robust testing is non-negotiable when using agents. Because agents can generate and modify code rapidly, a strong test suite is the only way to ensure the codebase remains stable during high-velocity AI-assisted development.

Dynamic Context Management with Firebase

Managing LLM context windows is critical for performance. Instead of loading an entire codebase into a single prompt, use Firebase and Firestore to create "sandboxed" agent skills.

• Dynamic Skill Loading: Package specific logic (e.g., "refund support" vs. "upselling") into discrete skills. By dynamically picking and loading these skills based on the user's current intent, you prevent context pollution and ensure the agent stays focused on the specific task at hand.
• Automated Metadata Generation: Use automated pipelines (e.g., triggering Firestore functions upon file storage uploads) to generate YAML and metadata for these skills. This removes the need to manually write boilerplate logic for every new agent capability.

The Shift to Design-First Engineering

As AI tools lower the barrier to implementation, the primary bottleneck has shifted from writing code to defining the problem.

• Prioritize Design: Spend approximately 60% of the project lifecycle in the design and research phase. Tools like NotebookLM and the Gemini app are recommended for exploring problem spaces, validating ideas, and creating clear prompts before a single line of code is written.
• Visual Prototyping: Use tools like Stitch to visualize ideas early. If you cannot describe or visually represent an idea clearly, it indicates the concept is not yet well-defined enough for an agent to build.
• Human Pattern Matching: Humans remain superior at pattern matching. When working with agents, actively monitor the file system and streaming output to ensure the agent is adhering to established patterns. If the agent deviates, it is usually a sign that it lacks the necessary context or that the directory-level documentation is insufficient.