claude-code-governance-template

<div align="center"> # ShopFlow **A reference framework for governing AI coding agents with Claude Code.** ShopFlow is a small, fully working e-commerce application (React + Express). Its primary purpose is to demonstrate how a team can govern an AI coding agent — through project context, policy rules, expert skills, and deterministic guardrails — so that generated code follows your conventions by default. </div> --- ## Table of contents - [Overview](#overview) - [Live Demo](#live-demo) - [The governance model](#the-governance-model) - [Tech stack](#tech-stack) - [Repository layout](#repository-layout) - [Getting started](#getting-started) - [Prerequisites](#prerequisites) - [Installation & running](#installation--running) - [MCP servers](#mcp-servers) - [Documentation](#documentation) - [Notes & constraints](#notes--constraints) --- ## Overview The application code is the stage; the `.claude/` directory is the point. Use this repository as a **template for your own project**: copy the governance layer (`CLAUDE.md`, `.claude/rules/`, `.claude/skills/`, `.claude/hooks/`, `.claude/settings.json`, `.mcp.json`), adapt it to your stack, and you get an agent that follows your team's conventions, refuses what your project forbids, and is physically prevented from unsafe actions. > **The rules, skills, and hooks here are samples for reference.** They encode one > project's opinionated conventions to illustrate the pattern. Review and adapt them to > your own team's standards, stack, and needs before adopting — see > [`docs/GOVERNANCE.md`](docs/GOVERNANCE.md#adapting-this-framework-to-your-own-app). --- ## Live Demo ▶ **[Watch the ShopFlow demo][recording]** *(Cognizant sign-in required)* — a full recording of the EMEA LearnFest 2026 "Claude Code for Developers" session. **Want to follow along?** Complete the one-time [setup](#getting-started), then run the prompts in **[`docs/DEMO.md`](docs/DEMO.md)** alongside the video. The demo runs in two acts: 1. **Explore → Plan → Code → Commit** — the core Claude Code workflow. 2. **The governance layers, live** — a walk down the pyramid: skill → rule → hook → MCP. > **Note:** the recording shows the project under its earlier repository name; the repo > is now `claude-code-governance-template`. The code and steps are otherwise identical. --- ## The governance model Four layers govern the agent's behaviour, escalating from *advice* to *physics*: | Layer | Lives in | Governs | Nature | Bypassable? | |-------|----------|---------|--------|-------------| | **Rules** | `.claude/rules/` + `CLAUDE.md` | What is allowed or forbidden | Policy | Honoured every turn | | **Skills** | `.claude/skills/` | How to do it well | Expertise | Followed by choice | | **Hooks** | `.claude/settings.json` + `.claude/hooks/` | What is enforced regardless | Deterministic | **No — cannot bypass** | | **Permissions** | `.claude/settings.json` | Which tools may run at all | Access gate | **No — gated by harness** | > **In one line:** skills are advice the agent chooses to follow, rules are policy it > must honour, and hooks are physics it cannot break. The clearest example is the **"no TypeScript"** constraint, governed at two layers at once: a **rule** (`forbidden-tech.md`) instructs the agent not to, and a **hook** (`guard-typescript.sh`) blocks any `.ts`/`.tsx` write outright. Policy asks; physics enforces. Together these map to the **4D framework** — Delegation, Description (`CLAUDE.md` + skills), Discernment (Plan Mode), and Diligence (the hooks). For a file-by-file breakdown and guidance on adapting the layer to your own project, see **[`docs/GOVERNANCE.md`](docs/GOVERNANCE.md)**. --- ## Tech stack | Layer | Technology | |-------|-----------| | Frontend | React 18, Vite, lucide-react, inline styles | | Backend | Node.js 18+, Express 4, REST API | | Data | `products.json` (no database — intentional) | | State | React Context + `useReducer` | | Tooling | ESLint, MCP (GitHub + filesystem) | The frontend is **API-backed** — it fetches all product data from the backend rather than using hardcoded arrays. The backend follows a **layered architecture**: `route → controller → service → repository`. --- ## Repository layout ``` . ├── CLAUDE.md Project context, auto-loaded into every session ├── README.md This file ├── docs/ │ ├── GOVERNANCE.md The .claude/ layer file by file; adapting it to your app │ ├── DEMO.md Step-by-step prompts to reproduce the demo │ ├── MCP-SETUP.md GitHub + filesystem MCP setup (PAT, env vars, Inspector) │ ├── Claude Code For Developers - EMEA Learn Fest 2026.pdf Session slide deck │ ├── images/ Screenshots + repo QR code used in the docs ├── .mcp.json MCP servers (github + filesystem) ├── .claude/ │ ├── settings.json Wires up the hooks │ ├── rules/ Policy — forbidden-tech.md (always-on), frontend.md, backend.md │ ├── skills/ Expertise — frontend/, backend/, legacy-explainer/ │ └── hooks/ Enforcement — guard-secrets, guard-typescript, post-write-lint ├── frontend/ React 18 + Vite │ └── src/ App.jsx · pages/ · components/ · hooks/ · api/ · context/ · utils/ └── backend/ Node.js + Express 4 ├── server.js Entry point (createApp + listen) ├── data/products.json Product catalogue (source of truth, 12 products) └── src/ app.js · routes/ · controllers/ · services/ · repositories/ · middleware/ · utils/ ``` --- ## Getting started ### Prerequisites | Requirement | Notes | |-------------|-------| | **Node.js 18+** and npm | <https://nodejs.org> | | **Claude Code License** | Raised the request for Claude Code and Chat via Service Now Request | | **Claude Code CLI** | Install with `npm install -g @anthropic-ai/claude-code`; verify with `claude --version` | | **Bash shell** | Required by the hooks. Git Bash on Windows is sufficient. | | **GitHub token** | Needed for the MCP / GitHub-issue demo step. See [MCP servers](#mcp-servers). | > **Note:** `.claude/rules/` is a recent Claude Code feature. If your version does not > support it, the "What NOT to do" section in `CLAUDE.md` serves as a reliable fallback. > **`claude` not found after install?** The npm global bin directory is not on your > `PATH`. Add it under **System Properties → Environment Variables → `Path`** — > `C:\Users\<your-userid>\AppData\Roaming\npm-cache` (standard npm) or > `C:\Users\<your-userid>\AppData\Local\nvm` (if you use NVM) — then restart the > terminal or VS Code. ### Installation & running Run the backend and frontend in separate terminals from the repository root: ```bash # Terminal 1 — backend (REST API on http://localhost:3001) cd backend npm install npm run start # Terminal 2 — frontend (Vite dev server on http://localhost:5173, proxies /api → :3001) cd frontend npm install npm run dev # Terminal 3 — Claude Code (run from the repository root) claude ``` Open <http://localhost:5173>; the homepage should load with all 12 product images. > The backend must be running, or the product grid will show an empty/error state — > there is no hardcoded product data on the frontend by design. **Which port do I open?** There are two intended modes: | Mode | Command | Open in browser | API calls go to | |------|---------|-----------------|-----------------| | **Dev** | `npm run dev` (frontend) + backend running | <http://localhost:5173> | `:5173/api/*` → Vite proxies to `:3001` | | **Prod** | `npm run build` (frontend) then `npm start` (backend) | <http://localhost:3001> | `:3001/api/*` (same origin) | > **Open `:5173`, not `:3001`, in development.** The backend serves the API *and* the > **built** React app from `frontend/dist/`. In dev that folder doesn't exist (you > haven't run `npm run build`), so hitting <http://localhost:3001> directly returns an > `ENOENT: …/frontend/dist/index.html` error. That's expected — use `:3001` directly > only after the production-style build below. **Production-style run (single server):** build the frontend and let Express serve the built app and the API together on port 3001: ```bash cd frontend && npm run build cd ../backend && npm start ``` ### MCP servers Two MCP servers are configured in `.mcp.json`: **filesystem** (no token, works out of the box) and **github** (needs a Personal Access Token). > **Do I need this?** Not for simply *running the app*, but **yes for the full demo** — > Demo 2's final step creates a GitHub issue through the **github** server. On first > launch Claude Code asks you to approve the servers from `.mcp.json`; approve them (your > choice is saved to the personal, git-ignored `.claude/settings.local.json`). **To set up the GitHub server** — create a PAT, expose it as `GITHUB_TOKEN`, add any machine-specific runtime settings, then run it — follow **[docs/MCP-SETUP.md](docs/MCP-SETUP.md)**. --- ## Documentation | Document | Contents | |----------|----------| | **README.md** *(this file)* | Overview, governance model, layout, setup | | [`docs/GOVERNANCE.md`](docs/GOVERNANCE.md) | The `.claude/` layer file by file; adapting it to your own app; troubleshooting | | [`docs/MCP-SETUP.md`](docs/MCP-SETUP.md) | Setting up the GitHub & filesystem MCP servers (PAT, env vars, Inspector) | | [`docs/DEMO.md`](docs/DEMO.md) | Step-by-step prompts to reproduce the demo | --- ## Notes & constraints ShopFlow is a demonstration application. It intentionally omits a database, authentication, and TypeScript — these constraints are the point. The value lies in the `.claude/` governance layer, not the storefront itself. [recording]: https://apc01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fteams.microsoft.com%2Fl%2Fmeetingrecap%3FdriveId%3Db%2521IZQYIRjdxke9Su886NikyImZwboOwQVInMUpNnYWo9K4-1btDHU4Ra6wWfhvKVqK%26driveItemId%3D01STYZSVOPXBBR5FBH4RCJZEW65HQBUKB4%26sitePath%3Dhttps%253A%252F%252Fcognizantonlinegbr-my.sharepoint.com%252F%253Av%253A%252Fg%252Fpersonal%252F406407_cognizant_com%252FIQDPuEMelCfkRJyS3ungGig8AZzh9Uqgc2xOHxJF-TQ0EFE%26fileUrl%3Dhttps%253A%252F%252Fcognizantonlinegbr-my.sharepoint.com%252F%253Av%253A%252Fg%252Fpersonal%252F406407_cognizant_com%252FIQDPuEMelCfkRJyS3ungGig8AZzh9Uqgc2xOHxJF-TQ0EFE%26iCalUid%3D040000008200E00074C5B7101A82E0080000000060F6699040F4DC01000000000000000010000000E6D4211753C1CE418E2A2155AEEA04A6%26threadId%3D19%253Ameeting_Mjk3Y2VkMjItNzcyZi00MzMxLWIxMDktMjc2ZmQ5MWJkODNk%2540thread.v2%26organizerId%3D8db76844-e041-4c3b-8f25-9bdb39987f4e%26tenantId%3Dde08c407-19b9-427d-9fe8-edf254300ca7%26callId%3D705af3e8-6e63-4313-8617-4ec4941b225b%26threadType%3DMeeting%26meetingType%3DScheduled%26subType%3DRecapSharingLink_RecapChiclet&data=05%7C02%7CAditi.ChidambaramSrinivasan%40cognizant.com%7C2471f86dc67341788d6a08decd724853%7Cde08c40719b9427d9fe8edf254300ca7%7C0%7C0%7C639174087949477081%7CUnknown%7CTWFpbGZsb3d8eyJFbXB0eU1hcGkiOnRydWUsIlYiOiIwLjAuMDAwMCIsIlAiOiJXaW4zMiIsIkFOIjoiTWFpbCIsIldUIjoyfQ%3D%3D%7C0%7C%7C%7C&sdata=8FYjKcS2rzHDczU1Lt5vjYqOjGerJ8bKUdPbrUGHryM%3D&reserved=0