Skip to content

Draft: Enterprise Guide to Agentic AI Development

Jump to bottom
K. C. Ramakrishna edited this page Aug 20, 2025 · 2 revisions

Background: We have an open source manual on how we integrated genAI into a production grade application - UDAN Case Study of genAI adoption across DevSecOps

We have been evaluating and adopting 'Agentic tools' like Gemini CLI, Google Jules, Sourcegraph Junie etc and decided to document the practical learnings and limitations for the Open Source community.
The agentic manual aims to be more prescriptive than a general GenAI guide. It's not just about "how to prompt better"; it's about "how to build a reliable, automated system where an AI is a core contributor." It must cover the environment, the instructions, the guardrails, and the human's role as an architect and reviewer.

Below is the outline based on our work so far. We will be detailing this out over the next few weeks (Sep/Oct 2025).

Enterprise Guide to Agentic AI Development

A practical handbook for integrating autonomous AI agents, such as the Gemini CLI, into a professional software development lifecycle.

Table of Contents

Part 1: Foundations of Agentic Development

  • 1.0 Introduction: Beyond the Copilot

    • 1.0.1 Purpose of This Guide
    • 1.0.2 What is an "Agentic Workflow"?
    • 1.0.3 From AI as a Tool to AI as a Team Member
    • 1.0.4 The Human's Role: The Architect and the Reviewer

  • 1.1 Core Principles

    • 1.1.1 Principle I: Explicit Instruction Over Ambiguity. Why agents require structured, unambiguous tasks.
    • 1.1.2 Principle II: The Environment is the Contract. The importance of a reproducible, containerized development environment.
    • 1.1.3 Principle III: Guardrails are Non-Negotiable. Establishing clear rules and constraints to ensure safety and consistency.
    • 1.1.4 Principle IV: Verifiability is Trust. The role of automated testing and CI in validating agent-generated work.

  • 1.2 The Foundational Artifacts

    • 1.2.1 The AGENTS.md File: The Agent's Operating Manual
    • 1.2.2 The CONVENTIONS.md File: The Project's Rulebook
    • 1.2.3 Issue Templates: Structuring Work for Machines
    • 1.2.4 Architecture Decision Records (ADRs): Providing Context and Constraints

Part 2: The Agent's Workshop: Environment & Tooling

  • 2.0 The Monorepo Strategy

    • 2.0.1 Why a Monorepo is useful for Agentic Workflows
    • 2.0.2 Achieving Atomic Commits and Unified Project Management

  • 2.1 The Reproducible Environment: Docker & docker-compose

    • 2.1.1 Defining Services for Local Development
    • 2.1.2 Using Health Checks to Create a Reliable Startup Sequence

  • 2.2 The Agent's Brain: The Gemini CLI Sandbox

    • 2.2.1 Understanding the Sandbox: An Isolated, Ephemeral Workshop
    • 2.2.2 Configuring the Sandbox with config.toml
    • 2.2.3 Installing System Dependencies (apt_packages)
    • 2.2.4 Installing Python Libraries (pip_packages)
    • 2.2.5 Securely Providing Credentials with gemini secret and PATs

  • 2.3 The Agent's Hands: Building Custom Tools

    • 2.3.1 The axtools Framework: How the Sandbox Loads Tools
    • 2.3.2 Designing a Tool: The gh CLI Wrapper Pattern
    • 2.3.3 A Curated Toolbox: Essential Tools for a Development Agent (File I/O, Git, gh, Shell Execution)
    • 2.3.4 How to Add and Test New Tools

Part 3: The Project Management Framework

  • 3.0 The Hierarchical Model: Epics, Stories, and Tasks

    • 3.0.1 Why a Hierarchy is Critical for Breaking Down Work
    • 3.0.2 Defining Each Level for Maximum Clarity

  • 3.1 Structuring Work for Agents

    • 3.1.1 The Anatomy of a World-Class Task: Specificity, Atomicity, and the "Definition of Done"
    • 3.1.2 Using GitHub Issue Forms to Guide Human Contributors
    • 3.1.3 The Role of Labels for Programmatic Categorization

  • 3.2 Project Kickoff: The Bulk Upload Process

    • 3.2.1 Structuring the Project Plan in a Hierarchical CSV
    • 3.2.2 The Python Uploader Script: A Reusable Tool for Project Initialization
    • 3.2.3 Understanding the Multi-Pass Algorithm: Create, Then Link

Part 4: The Agentic Development Lifecycle in Practice

  • 4.0 The Master Workflow: From Issue to Pull Request

    • 4.0.1 Phase 1: Setup & Synchronization (gh repo sync)
    • 4.0.2 Phase 2: Implementation (The Initial Code Generation)
    • 4.0.3 Phase 3: The Quality Assurance & Self-Correction Loop
    • 4.0.4 Phase 4: Final Validation (Running Linters and Tests)
    • 4.0.5 Phase 5: Submission (Committing and Creating a PR)

  • 4.1 The Self-Correction Loop: Quality Assurance Profiles

    • 4.1.1 The workflow: Label System: Applying Context-Aware Quality Checks
    • 4.1.2 Profile workflow:core: For Critical Backend Logic
    • 4.1.3 Profile workflow:infra: For Infrastructure and Scripts
    • 4.1.4 Profile workflow:docs: For Documentation Changes
    • 4.1.5 How to Define and Add New Profiles

  • 4.2 The Human-in-the-Loop: Reviewing AI-Generated Pull Requests

    • 4.2.1 Shifting the Focus of Code Review: From Syntax to Semantics
    • 4.2.2 How to Efficiently Review an Agent's PR
    • 4.2.3 Trusting the Process: Verifying that the Agent Followed the Workflow
    • 4.2.4 Providing Feedback for Iteration

Part 5: Advanced Topics & Best Practices

  • 5.0 Security for Agentic Systems

    • 5.0.1 The Principle of Least Privilege for PATs
    • 5.0.2 The Importance of the "Safety Guardrails" in AGENTS.md
    • 5.0.3 Auditing and Monitoring Agent Activity

  • 5.1 Debugging Agentic Workflows

    • 5.1.1 When the Agent Fails: Common Pitfalls
    • 5.1.2 Interpreting Agent Errors and Providing Better Instructions
    • 5.1.3 The Feedback Loop: Using Failures to Improve Prompts and Tools

  • 5.2 Extending the Agent's Capabilities

    • 5.2.1 Designing and Adding New Custom Tools to the Sandbox
    • 5.2.2 Integrating with Other APIs
    • 5.2.3 The Future: From Single-Task Agents to Multi-Issue Orchestration

Appendix

  • A. Full AGENTS.md Template
  • B. Full CONVENTIONS.md Template
  • C. Sample Hierarchical CSV File
  • D. Glossary of Terms (Agent, Sandbox, Tool, Prompt, etc.)

Clone this wiki locally