Jordandevlog/ai-dev-template

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.

Supports multiple technology stacks: Python (FastAPI), Node.js/TypeScript (Express), C++23, C# (.NET 8), and Web (React + TypeScript + Tailwind).

---

🏗️ 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/                    # 🔵 Python (FastAPI) stack
│   ├── core/               # Config, models, database
│   ├── api/                # Routes, schemas, dependencies
│   ├── services/           # Business logic
│   ├── utils/              # Validators, exceptions, logger
│   └── main.py             # Application entry point
│
├── nodejs/                 # 🟢 Node.js/TypeScript (Express) stack
│   ├── src/
│   │   ├── controllers/    # HTTP route handlers
│   │   ├── services/       # Business logic
│   │   ├── routes/         # Route definitions
│   │   ├── middleware/     # Express middleware
│   │   ├── models/         # Prisma schemas / Zod models
│   │   └── utils/          # Logger, errors, validators
│   ├── tests/
│   ├── package.json
│   ├── tsconfig.json
│   └── vitest.config.ts
│
├── cpp/                    # ⚪ C++23 stack
│   ├── include/            # Header files
│   │   ├── core/           # Config, models
│   │   ├── api/            # Route definitions
│   │   └── utils/          # Logger, exceptions, validators
│   ├── src/                # Implementation files
│   ├── tests/              # GoogleTest files
│   ├── CMakeLists.txt      # Build configuration
│   └── scripts/            # Build scripts
│
├── csharp/                 # 🔵 C# / .NET 8 stack
│   ├── src/
│   │   ├── Core/           # Configuration, models, exceptions
│   │   ├── Api/            # Controllers, middleware
│   │   ├── Services/       # Business logic
│   │   └── Utils/          # Helpers
│   ├── tests/              # xUnit tests
│   ├── ai-dev-project.csproj
│   ├── appsettings.json
│   └── .editorconfig
│
├── web/                    # 🟣 React + TypeScript + Tailwind stack
│   ├── src/
│   │   ├── components/     # React components
│   │   ├── styles/          # Tailwind CSS + custom
│   │   ├── hooks/           # Custom React hooks
│   │   ├── api/             # API client + React Query
│   │   ├── types/           # TypeScript types
│   │   └── utils/           # Formatters, helpers
│   ├── tests/               # Component + unit tests
│   ├── public/              # Static assets
│   ├── index.html
│   ├── vite.config.ts
│   └── tailwind.config.js
│
├── 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 (all stacks)
│   ├── start-ollama.sh        # Start optimized local Ollama server
│   ├── nodejs/setup.sh        # Node.js setup
│   ├── cpp/setup.sh           # C++ build + test
│   ├── csharp/setup.sh        # C# restore + build
│   └── web/setup.sh           # Web frontend setup
│
├── .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
└── .gitignore

---

🚀 Quick Start

1. Clone and Setup

git clone https://huggingface.co/Jordandevlog/ai-dev-template my-project
cd my-project
chmod +x scripts/*.sh scripts/*/*.sh

# Setup EVERYTHING (Python + Node.js + C++ + C# + Web)
./scripts/setup.sh

# Or setup a specific stack only:
./scripts/setup.sh --python
./scripts/setup.sh --nodejs
./scripts/setup.sh --cpp
./scripts/setup.sh --csharp
./scripts/setup.sh --web

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) — choose your stack:

# Python
python agents/multiagent_workflow.py "Build a blog API" --stack python

# Node.js
python agents/multiagent_workflow.py "Build a real-time chat API" --stack nodejs

# C++
python agents/multiagent_workflow.py "Build a high-performance data pipeline" --stack cpp

# C#
python agents/multiagent_workflow.py "Build a microservices API" --stack csharp

# Web
python agents/multiagent_workflow.py "Build a dashboard UI" --stack web

---

🖥️ Stack Quick Reference

Python (FastAPI + SQLAlchemy)

Task	Command
Install deps	pip install -r requirements.txt (or use setup.sh)
Run dev	uvicorn src.main:app --reload
Run tests	pytest --cov=src --cov-report=term-missing
Format	black src/ tests/
Lint	ruff check src/ tests/
Type check	mypy src/

Node.js (Express + TypeScript + Prisma)

Task	Command
Install deps	cd nodejs && npm install
Run dev	cd nodejs && npm run dev
Build	cd nodejs && npm run build
Run tests	cd nodejs && npm test
Lint	cd nodejs && npm run lint
Format	cd nodejs && npm run format

C++ (C++23 + CMake + GoogleTest)

Task	Command
Build	./cpp/scripts/build.sh
Build debug	./cpp/scripts/build.sh Debug
Run tests	cd cpp/build && ctest --output-on-failure
Format	clang-format -i cpp/src/**/*.cpp cpp/include/**/*.hpp

C# (.NET 8 + ASP.NET Core + xUnit)

Task	Command
Restore	dotnet restore csharp/
Build	dotnet build csharp/
Run tests	dotnet test csharp/ --collect:"XPlat Code Coverage"
Run app	dotnet run --project csharp/

Web (React + TypeScript + Vite + Tailwind)

Task	Command
Install deps	cd web && npm install
Run dev	cd web && npm run dev
Build	cd web && npm run build
Preview	cd web && npm run preview
Run tests	cd web && npm test
Lint	cd web && npm run lint

---

🤖 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, data flow, stack selection	When adding/removing modules
docs/CONTEXT.md	How to code per stack	When standards change
.cursorrules	Cursor IDE behavior	When switching editors
.claude.md	Claude Code behavior	When switching agents

---

🛡️ MCP Servers

Connect your IDE to powerful tools:

• Hugging Face Hub: Search models, datasets, papers
• Filesystem: Read/write your 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

---

📚 Recommended Workflow

1. Write PRD → Define what you're building in docs/PRD.md
2. Choose Stack → Select python/nodejs/cpp/csharp/web based on requirements
3. AI Architecture → Ask Claude/OpenCode to design architecture → Update docs/ARCHITECTURE.md
4. AI Implementation → Use local agent to write code in chosen stack
5. AI Testing → Run multi-agent workflow to generate tests
6. Human Review → Check code, run tests, fix issues
7. Commit → git commit -m "feat: implement user registration"
8. Repeat → Next feature

---

📦 Stack Dependencies

Stack	Framework	ORM	Testing	Linting	Key Features
Python	FastAPI 0.110	SQLAlchemy 2.0	pytest + cov	black, ruff, mypy	Pydantic v2, dependency injection
Node.js	Express 4.19	Prisma 5.11	Vitest	ESLint + Prettier	Zod validation, Winston logging
C++	Custom / Crow	SQLite	GoogleTest	clang-format	C++23, std::expected, RAII
C#	ASP.NET Core 8	EF Core	xUnit + Moq	.editorconfig	Serilog, FluentValidation
Web	React 18 + Vite	React Query	Vitest + RTL	ESLint + Prettier	Tailwind, Zustand, Lucide

---

📖 References

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

---

🗂️ Template Repo

• GitHub-style repo: https://huggingface.co/Jordandevlog/ai-dev-template
• Clone: git clone https://huggingface.co/Jordandevlog/ai-dev-template my-project