You can deploy this model and start earning money today!

Jordandevlog/
ai-dev-template

2505.19443

Views

No views yet

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

bash

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

bash

# 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

bash

# 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):

bash

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

Multi-Agent Team (complex projects) — choose your stack:

bash

# 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

Claude/OpenCode for architecture design and planning
Local Ollama for fast iteration and implementation
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

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

🗂️ Template Repo

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