Skip to content

Tounisiano/agentic-dev-template

BranchesTags

Repository files navigation

Agentic Dev Template

CI Security License: MIT Claude Code PRs Welcome GitHub Stars

One experienced developer + AI = something the market doesn't have a name for yet.

A production-tested methodology for building software with Claude Code as your agentic co-developer.
Works with any stack — web, API, mobile, data, infra.

🇫🇷 Documentation en français

Why this template

You already know how to ask an AI a question.
This template solves a different problem: how to make AI a reliable team member across a real, multi-month project.

The core principle: everything starts with a spec (docs/SPEC.md), rules are set once in CLAUDE.md, and agents (slash commands) execute repeatable workflows.

SPEC.md → CLAUDE.md → /spec-to-code → code → /test-gen → /pre-push → CI/CD
    ↑                                                              ↓
    └──────────────── /doc-sync ←──────────── feature shipped ────┘

CLAUDE.md is the source of truth. It's read at every slash command. Rules in it apply to every line of generated code. This is the difference between an assistant that answers and an agent that knows your project.

Observed results — 12-month production project

Metric Result
Production bugs since launch 0
Test coverage ≥ 90% — a rule, not a goal
Technical debt Zero — conventions set from day one
Effective capacity 1 dev = team of 8 (full-stack, K8s, CI/CD, RAG, auth, monitoring)

Demo

📽️ GIF demo coming — showing /spec-to-code turning a plain-English spec into tested, documented, production-ready code in under 2 minutes.
Want to contribute one? Open an issue with label demo.

Prerequisites

  • Claude Code — npm install -g @anthropic/claude-code
  • Git
  • CI: GitHub Actions or Jenkins (both included)

Quick start — 5 minutes

1. Use this template

Click the green "Use this template" button at the top of this page, or:

git clone https://github.com/Tounisiano/agentic-dev-template.git my-project
cd my-project
rm -rf .git && git init && git add . && git commit -m "chore: init from agentic-dev-template"

2. Adapt CLAUDE.md to your project

Open CLAUDE.md and fill in the [TO ADAPT] sections:

  • Project description (2–3 sentences: problem, audience, main constraint)
  • Your actual tech stack
  • Your launch / test / lint commands
  • Any domain-specific architecture rules
cp .env.example .env
# Edit .env and fill in your secrets
# Generate strong secrets with: openssl rand -hex 32

3. Install git hooks (optional, recommended)

pip install pre-commit && pre-commit install

Catches hardcoded secrets and enforces code quality before every commit.

4. Write your first spec

Open docs/SPEC.md, describe what you want to build in plain language, then inside Claude Code:

/spec-to-code docs/SPEC.md

Claude reads your spec, reads existing code, proposes architecture, generates tested code — all respecting the rules in CLAUDE.md.

Slash commands (agents)

Development

Command What it does
/spec-to-code Spec → architecture + code + tests + docs
/new-feature Guided new feature from an inline description
/refactor Guided refactoring without changing behavior
/debug Structured: reproduce → isolate → fix → regression test

Quality

Command What it does
/test-gen Tests for any file: happy path, errors, edge cases, auth
/security-check OWASP Top 10 audit on changed code
/code-review Autonomous code review
/pre-push Complete checklist before pushing

Operations

Command What it does
/db-migration Safe migration generated from a model change
/incident Production incident response protocol
/doc-sync Updates all docs after a feature ships
/adr Documents an architecture decision

Template structure

.
├── CLAUDE.md                    ← Project constitution — adapt this first
├── CONTRIBUTING.md
├── docker-compose.yml           ← Local stack (db + redis + backend + frontend)
├── .env.example                 ← Environment variable template
├── .pre-commit-config.yaml      ← Git hooks: secret detection + quality
│
├── .claude/
│   ├── settings.json            ← Claude Code permissions + hooks
│   └── commands/                ← 12 slash agents (autonomous workflows)
│       ├── spec-to-code.md      ← Spec → architecture + code + tests + docs
│       ├── new-feature.md
│       ├── refactor.md
│       ├── debug.md
│       ├── test-gen.md
│       ├── security-check.md    ← OWASP Top 10 audit
│       ├── code-review.md
│       ├── pre-push.md
│       ├── db-migration.md
│       ├── incident.md
│       ├── doc-sync.md
│       └── adr.md
│
├── docs/
│   ├── SPEC.md                  ← Spec template — start every feature here
│   ├── DESIGN.md                ← System architecture
│   ├── CONVENTIONS.md           ← Patterns to follow exactly
│   ├── DECISIONS.md             ← Architecture decisions (ADR log)
│   ├── API.md                   ← API reference
│   ├── SECURITY.md              ← Security rules + secrets management
│   └── ROADMAP.md               ← Done / todo / out of scope
│
├── .github/
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── ISSUE_TEMPLATE/          ← Bug report + feature request
│   └── workflows/
│       ├── ci.yml               ← Tests + lint + coverage (≥ 85%)
│       ├── security.yml         ← SAST + Gitleaks + Trivy
│       └── deploy.yml           ← Deployment pipeline
│
├── jenkins/                     ← CI/CD for Jenkins environments
└── scripts/
    ├── setup.sh                 ← Initial project setup
    └── generate-secrets.sh      ← Secret generation helper

The Spec Driven Development workflow

1. SPEC.md       Describe the feature in plain language
                 (context, expected behavior, constraints, edge cases)

2. /spec-to-code Claude reads spec + existing code
                 → proposes architecture
                 → generates code respecting CLAUDE.md

3. /test-gen     Generates tests:
                 happy path / errors / edge cases / access control

4. CI/CD         Pipeline: lint → tests → coverage ≥ 85% → security scan

5. /doc-sync     Updates DESIGN.md, API.md, ROADMAP.md automatically

6. /pre-push     Final checklist before merge

Philosophy

Conventions are non-negotiable. TDD, no hardcoded secrets, clean architecture, up-to-date docs. Set them once in CLAUDE.md — slash commands enforce them automatically on every feature, forever.

Docs are code. docs/DESIGN.md isn't an external wiki — it's context Claude reads before generating anything. Stale docs → imprecise agent.

The spec is the contract. Every feature starts in SPEC.md. This forces clarity before code and gives Claude the context it needs to make correct architectural decisions.

After forking — recommended GitHub settings

  1. Enable template mode: Settings → check "Template repository" → users get a green "Use this template" button instead of Fork
  2. Add topics for discoverability: claude-code ai-tools developer-template agentic-ai llm devops spec-driven-development productivity
  3. Enable Discussions: Settings → Features → Discussions (lets the community share adapted versions)

Contributing

This template evolves with real-world feedback. Issues and PRs welcome — see CONTRIBUTING.md.

What we accept:

  • New slash commands covering common workflows
  • CI/CD improvements (GitHub Actions / Jenkins)
  • New patterns in docs/CONVENTIONS.md
  • Bug fixes in scripts
  • Documentation improvements

What we don't accept:

  • Dependencies on a specific framework or language — the template is stack-agnostic
  • Overly specialized slash commands (those belong in your fork)

⭐ If this helped you

If this template saved you time or changed how you think about AI-assisted development — a star takes 1 second and helps others discover it.

🇫🇷 Version française

Lire la documentation complète en français

Un développeur expérimenté + IA = quelque chose que le marché n'a pas encore de nom pour désigner.

Ce template est une méthodologie opérationnelle pour construire des projets logiciels avec Claude Code comme co-développeur agentique. Il s'applique à n'importe quel projet : web, API, mobile, data, infra.

Ce que c'est

Pas un framework. Pas un générateur de code. Une façon de travailler qui transforme Claude Code en un membre d'équipe qui connaît votre projet aussi bien que vous.

Le principe central : tout commence par une spec (docs/SPEC.md), les règles sont posées une fois dans CLAUDE.md, et les agents (slash commands) exécutent des workflows répétables.

SPEC.md → CLAUDE.md → /spec-to-code → code → /test-gen → /pre-push → CI/CD
    ↑                                                              ↓
    └──────────────── /doc-sync ←──────────── feature livrée ─────┘

Résultats observés sur un projet de 12 mois

  • Zéro bug en prod depuis le lancement
  • Couverture de tests ≥ 90% — pas parce qu'il y a eu le temps, mais parce que c'est une règle non négociable
  • Zéro dette technique — les conventions ont été posées dès le départ
  • 1 développeur = équipe de 8 sur un projet full-stack avec K8s, CI/CD, RAG, auth, monitoring

Prérequis

  • Claude Code installé (npm install -g @anthropic/claude-code)
  • Git
  • Pour la CI : GitHub Actions ou Jenkins (les deux sont inclus)

Démarrage en 5 minutes

1 — Utiliser ce template

Cliquer sur le bouton vert "Use this template" en haut de la page, ou :

git clone https://github.com/Tounisiano/agentic-dev-template.git mon-projet
cd mon-projet
rm -rf .git && git init && git add . && git commit -m "chore: init from agentic-dev-template"

2 — Adapter CLAUDE.md à votre projet

Ouvrir CLAUDE.md et remplir les sections [À ADAPTER] :

  • Description du projet (2-3 phrases : problème, audience, contrainte principale)
  • Stack technique réelle
  • Commandes de lancement / tests / lint
  • Règles spécifiques à votre domaine
cp .env.example .env
# Éditer .env — générer les secrets avec : openssl rand -hex 32

3 — Installer les hooks git (optionnel, recommandé)

pip install pre-commit && pre-commit install

4 — Rédiger votre première spec

# Dans docs/SPEC.md, décrire la feature en langage naturel
# Puis dans Claude Code :
/spec-to-code docs/SPEC.md

5 — Les agents disponibles

Commande Action
/spec-to-code Spec → architecture + code + tests + doc
/new-feature Nouvelle feature guidée
/refactor Refactoring guidé sans changer le comportement
/debug Débogage : reproduction → isolation → fix → test
/test-gen Génère les tests pour n'importe quel fichier
/security-check Audit sécurité OWASP Top 10
/code-review Review de code autonome
/pre-push Checklist avant push
/db-migration Migration sûre depuis un changement de modèle
/incident Protocole de réponse à un incident de production
/doc-sync Met à jour toute la doc après une feature
/adr Documente une décision d'architecture

Philosophie

CLAUDE.md est la source de vérité. Tout ce qui s'y trouve s'applique à chaque interaction. C'est la différence entre un assistant qui répond et un agent qui connaît votre projet.

Les conventions ne se négocient pas. TDD, pas de secrets en dur, clean architecture, docs à jour — ces règles sont dans CLAUDE.md et les slash commands les vérifient automatiquement.

La doc est du code. docs/DESIGN.md n'est pas un wiki externe — c'est lu par Claude à chaque slash command. Une doc à jour = un agent plus précis.

Après le fork — paramètres GitHub recommandés

  1. Activer le mode template : Settings → cocher "Template repository" → les utilisateurs voient un bouton "Use this template" vert
  2. Ajouter des topics pour la découvrabilité : claude-code ai-tools developer-template agentic-ai llm devops spec-driven-development productivity
  3. Activer Discussions : Settings → Features → Discussions

Contribuer

Ce template évolue avec les retours terrain. Issues et PRs bienvenues — voir CONTRIBUTING.md.

Built from 12 months of agentic development in production — one developer, full stack, zero production bugs.

About

Turn Claude Code into a reliable team member. 12 agents. Spec-driven workflow. Any stack.

Topics

productivity devops developer-template ai-tools llm agentic-ai claude-code spec-driven-development

Resources

Readme

License

MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages