Skip to content

AGENTS.md

Latest commit

 

History

History
189 lines (139 loc) · 6.66 KB

AGENTS.md

File metadata and controls

189 lines (139 loc) · 6.66 KB

AI-Assisted Development Documentation

This document describes how AI tools were used to build the ML Model Registry & Deployment Dashboard, fulfilling the AI Dev Tools Zoomcamp 2025 project requirements.

AI Tools Used

Primary: Claude (Anthropic)

Claude served as the primary AI coding assistant throughout the project development.

How Claude was used:

  1. Architecture Design

    • Discussed system requirements and trade-offs
    • Generated system architecture diagrams
    • Recommended tech stack based on project constraints

  2. Code Generation

    • Generated boilerplate code for FastAPI backend
    • Created React components with TypeScript
    • Wrote database models and migrations
    • Generated OpenAPI specifications

  3. Testing

    • Generated unit tests for backend services
    • Created integration tests for API endpoints
    • Wrote frontend component tests

  4. Documentation

    • Created README and setup instructions
    • Generated API documentation
    • Wrote inline code comments

  5. Debugging & Problem Solving

    • Diagnosed issues with Docker configurations
    • Fixed TypeScript type errors
    • Resolved database connection issues

Prompting Strategies

Effective prompts used:

  1. Context-first prompts: Always provided context about the project before asking for code

    "We're building an ML Model Registry. The backend uses FastAPI with SQLAlchemy.
Generate a Pydantic model for representing an ML model with fields for:
name, version, framework, metrics, and deployment status."

  2. Iterative refinement: Started with basic implementations, then refined

    "The model registration endpoint works, but we need to add validation for:
- Model name must be unique per user
- Version must follow semver format
- Metrics must be a valid JSON object"

  3. Example-driven prompts: Provided examples of desired output format

    "Generate a React component similar to this pattern:
[example component code]
But for displaying a list of ML models with filtering by framework"

MCP (Model Context Protocol) Integration

What is MCP?

MCP (Model Context Protocol) is a standard protocol that allows AI assistants to interact with external tools and data sources. In this project, MCP was used to enhance Claude's capabilities.

MCP Tools Used

  1. File System Access

    • Reading and writing project files
    • Navigating project structure
    • Creating new files and directories

  2. Web Search

    • Researching best practices for ML model registries
    • Finding documentation for libraries (FastAPI, React, SQLAlchemy)
    • Checking latest versions of dependencies

  3. Code Execution

    • Running Python scripts to test backend logic
    • Executing npm commands for frontend setup
    • Running Docker commands for containerization

MCP Workflow Example

Here's an example of how MCP enhanced the development workflow:

User: "Set up the FastAPI backend with SQLAlchemy and create the model schema"

Claude's MCP Actions:
1. [view] Check current project structure
2. [create_file] Create backend/requirements.txt with dependencies
3. [create_file] Create backend/app/models/ml_model.py with SQLAlchemy model
4. [create_file] Create backend/app/database.py with connection setup
5. [bash_tool] Run "pip install -r requirements.txt" to verify dependencies
6. [bash_tool] Run initial database migration

This MCP-enabled workflow allowed for:

  • Real-time file creation without copy-pasting
  • Immediate validation by running commands
  • Contextual awareness of existing project files

Benefits of MCP in This Project

  1. Faster iteration: Changes could be made and tested immediately
  2. Reduced errors: Claude could verify code by actually running it
  3. Better context: Claude maintained awareness of the full project structure
  4. Seamless workflow: No need to manually copy code between AI and IDE

Development Sessions Log

Session 1: Project Setup & Architecture

  • Defined project requirements and scope
  • Created initial README with problem description
  • Designed system architecture
  • Selected tech stack

Session 2: API Contract (OpenAPI)

  • Designed API endpoints based on frontend requirements
  • Created OpenAPI 3.0 specification
  • Defined request/response schemas

Session 3: Backend Development

  • Set up FastAPI project structure
  • Created SQLAlchemy models
  • Implemented CRUD endpoints
  • Added input validation with Pydantic

Session 4: Frontend Development

  • Initialized React + TypeScript project
  • Created centralized API service
  • Built UI components (Dashboard, ModelList, ModelForm)
  • Added state management

Session 5: Testing

  • Wrote unit tests for backend services
  • Created integration tests for API
  • Added frontend component tests
  • Set up test coverage reporting

Session 6: Containerization & Deployment

  • Created Dockerfiles for frontend and backend
  • Set up docker-compose for local development
  • Configured CI/CD pipeline with GitHub Actions
  • Deployed to cloud platform

Lessons Learned

What Worked Well

  1. Contract-first development: Starting with the OpenAPI spec made frontend-backend integration smooth
  2. Iterative prompting: Building features incrementally led to better results than asking for everything at once
  3. MCP file access: Being able to read/write files directly saved significant time

Challenges & Solutions

  1. Context window limits: For large files, had to work on sections at a time

    • Solution: Modular code architecture with smaller files

  2. Outdated library knowledge: Some library APIs had changed

    • Solution: Used web search to verify current documentation

  3. Complex debugging: Some issues required multiple back-and-forth iterations

    • Solution: Provided detailed error messages and context

Reproducibility

To reproduce this AI-assisted development workflow:

  1. Use Claude or similar AI assistant with MCP capabilities
  2. Start with clear project requirements and constraints
  3. Use contract-first approach (design API spec before implementation)
  4. Work iteratively - build, test, refine
  5. Provide context and examples in prompts
  6. Verify generated code by running tests

Conclusion

AI-assisted development significantly accelerated the creation of this ML Model Registry. The combination of Claude's code generation capabilities with MCP's tool integration created an efficient development workflow. The key to success was clear communication, iterative development, and maintaining good software engineering practices even when using AI tools.

This document fulfills the "AI system development (tools, workflow, MCP)" criterion for the AI Dev Tools Zoomcamp 2025 project.