Jordandevlog/ai-dev-template-backup

AI-Assisted Development Project Template

A production-ready project structure optimized for AI agents (local Ollama, Claude, OpenCode) to help you build software projects with maximum productivity.

🏗️ Project Structure

.
├── docs/
│   ├── PRD.md              # Product Requirements Document (SOURCE OF TRUTH)
│   ├── ARCHITECTURE.md     # File map, data flow, responsibilities
│   ├── CONTEXT.md          # Coding standards, constraints, forbidden patterns
│   └── decisions/          # Architecture Decision Records (ADRs)
├── src/
│   ├── core/               # Config, models, database
│   ├── api/                # Routes, schemas, dependencies
│   ├── services/           # Business logic
│   ├── utils/              # Validators, exceptions, logger
│   └── main.py             # Application entry point
├── tests/
│   ├── unit/               # Fast, isolated tests
│   ├── integration/        # DB + external API tests
│   └── e2e/                # Full flow tests
├── agents/
│   ├── smolagent_runner.py     # Single agent with local Ollama
│   └── multiagent_workflow.py  # Multi-agent team (architect→coder→tester→reviewer)
├── scripts/
│   ├── setup.sh            # One-command environment setup
│   └── start-ollama.sh     # Optimized Ollama server startup
├── .cursorrules            # Cursor IDE AI instructions
├── .claude.md              # Claude Code AI instructions
├── mcp.json                # MCP server configuration
├── opencode.json           # OpenCode local model config
└── pyproject.toml          # Python project + tool configuration

🚀 Quick Start

1. Clone and Setup

git clone <your-repo>
cd ai-dev-template
chmod +x scripts/*.sh
./scripts/setup.sh

This sets up:

• Python virtual environment (.venv/)
• All dependencies (FastAPI, pytest, black, ruff, mypy, smolagents)
• Starter source files (src/core/, src/api/, etc.)
• Git repository with pre-commit hooks
• .env template

2. Configure for Your Project

# Edit requirements
nano docs/PRD.md

# Edit architecture  
nano docs/ARCHITECTURE.md

# Edit coding standards
nano docs/CONTEXT.md

# Set environment variables
cp .env .env.local && nano .env.local

3. Start Local AI

# Start Ollama with optimized settings
./scripts/start-ollama.sh gemma4:4b

# Verify it's running
curl http://localhost:11434/api/tags

4. Run AI Agents

Single Agent (quick tasks):

source .venv/bin/activate
python agents/smolagent_runner.py "Create a user registration API endpoint"

Multi-Agent Team (complex projects):

source .venv/bin/activate
python agents/multiagent_workflow.py "Build a complete blog platform with authentication"

🤖 Agent Configuration

Local (Ollama)

• Model: gemma4:4b (fast, good for coding)
• API: http://localhost:11434/v1
• Context: 128K tokens
• Best for: Quick coding, refactoring, debugging

Cloud (Claude / OpenCode)

• Config: .claude.md in repo root
• MCP Servers: Hugging Face Hub, filesystem, git
• Best for: Complex architecture, design decisions, code review

Hybrid Workflow

1. Claude/OpenCode for architecture design and planning
2. Local Ollama for fast iteration and implementation
3. Both for code review and testing

📝 Key Files for AI Context

File	Purpose	When to Update
docs/PRD.md	What to build	When requirements change
docs/ARCHITECTURE.md	Where files go	When adding/removing modules
docs/CONTEXT.md	How to code	When standards change
.cursorrules	Cursor IDE behavior	When switching editors
.claude.md	Claude Code behavior	When switching agents

🔧 Tooling

Task	Command
Run tests	pytest --cov=src --cov-report=term-missing
Format code	black src/ tests/
Lint code	ruff check src/ tests/
Type check	mypy src/
Run app	uvicorn src.main:app --reload
Start Ollama	./scripts/start-ollama.sh

📚 Recommended Workflow

1. Write PRD → Define what you're building in docs/PRD.md
2. AI Architecture → Ask Claude/OpenCode to design architecture → Update docs/ARCHITECTURE.md
3. AI Implementation → Use local agent (smolagent_runner.py) to write code
4. AI Testing → Run multiagent_workflow.py to generate tests
5. Human Review → Check code, run pytest, fix issues
6. Commit → git commit -m "feat: implement user registration"
7. Repeat → Next feature

🛡️ MCP Servers

Connect your IDE to powerful tools:

• Hugging Face Hub: Search models, datasets, papers
• Filesystem: Read/write project files
• Git: Version control operations
• Code Execution: Test snippets before applying

Setup in your IDE (Cursor/VS Code/Claude Code):

• Cursor: Add MCP servers from mcp.json
• Claude Code: claude mcp add hf-mcp-server -t http "https://huggingface.co/mcp?login"
• OpenCode: Configured in opencode.json

📦 Dependencies

Core

• FastAPI — Modern web framework
• Pydantic v2 — Data validation and settings
• SQLAlchemy 2.0 — Database ORM
• pytest — Testing framework

AI/Agents

• smolagents — Lightweight agent framework
• Ollama — Local LLM server

Dev Tools

• black — Code formatter
• ruff — Fast linter
• mypy — Static type checker
• pre-commit — Git hooks

📖 References

• smolagents Docs
• Hugging Face MCP
• Ollama
• OpenCode
• Vibe Coding Paper