Your AI Writes You Ship
Web · Admin · Marketing Site · WeChat Mini-Program One prompt. Any platform. Mobile App coming soon.
Everyone's tried it. You open Claude Code or Cursor, describe what you want, and watch the AI write hundreds of lines in seconds. It looks impressive. Then you run it — and it breaks.
This isn't bad luck. It's structural.
The real reasons your AI-generated code falls short:
- No project-level spec — The AI doesn't know your folder conventions, naming patterns, or architecture decisions. It guesses, and guesses differently every time.
- No enforced constraints — Without lint rules, type schemas, and output contracts baked into the project, the AI freestyle-codes its way into an inconsistent mess.
- No shared language — Your AI tool has no idea what "production-grade" means for your project unless you tell it explicitly.
The result: code that compiles on Monday, breaks on Tuesday, and is impossible to extend by Friday.
The problem isn't the AI. It's the absence of a spec the AI can follow.
SPECC.SH solves this at the architecture level. There's no separate doc to write or maintain. The folder structure, type schemas, lint rules, and module contracts are the prompt — the codebase itself tells AI exactly what to do, every time.
1. Clone this template
2. Open your AI tool (Claude Code, Cursor, Copilot, Codex...)
3. Describe what you want to build in plain language
4. AI generates the code — guided by the built-in spec
5. Run: make lint && make tsc
6. Ship
The architecture is the prompt. Every folder, type contract, and lint rule tells AI what to do — consistent, type-safe, lint-passing code on the first try. No manual review needed.
curl -fsSL https://specc.sh | bashOr manually:
git clone https://github.com/luckyyyyy/specc.sh.git
cd specc.sh
make init # install deps + start Docker services + sync DB
make dev # start everything| Service | URL |
|---|---|
| Web (React) | http://localhost:5173 |
| API (Hono) | http://localhost:4000 |
| MinIO Console | http://localhost:9001 |
A production-ready TypeScript monorepo — batteries included:
specc.sh/
├── packages/
│ ├── server/ # Hono + tRPC + Prisma + PostgreSQL 18
│ ├── web/ # React 19 + Vite 8 + TailwindCSS 4 (SSR + CSR)
│ ├── miniapp/ # WeChat Mini-Program · Taro + React
│ ├── types/ # Shared Zod v4 schemas
│ ├── components/ # UI design system
│ └── i18n/ # EN + ZH out of the box
├── docker-compose.yml
├── Makefile
└── .github/
└── copilot-instructions.md ← Architecture rules, not docs
| Platform | Technology | Rendering |
|---|---|---|
| Web Frontend | React 19 + Vite 8 | CSR — instant HMR, <50ms dev feedback |
| Admin Dashboard | React 19 + Vite 8 | CSR — auth-gated SPA |
| Marketing / Landing Site | React Router v7 + Hono | SSR — SEO-indexed, first paint instant |
| WeChat Mini-Program | Taro + React | Native mini-program, shared tRPC + types |
| Mobile App | (coming soon) | — |
All platforms share the same Zod type schemas, tRPC procedures, and i18n resources. One prompt ships any platform feature.
| What you get | Detail |
|---|---|
| Auth + Sessions | Login, register, cookie sessions |
| Multi-Tenant Workspaces | Isolation, invites, role-based access |
| File Storage | MinIO locally → swap to S3 / OSS via env |
| i18n | EN / ZH, add more locales with zero component changes |
| Dark / Light / System Theme | CSS variable-driven |
| End-to-End Type Safety | tRPC + Zod — compiler catches AI mistakes instantly |
| WeChat Mini-Program | Taro + React, shares types + tRPC with the web app |
| SSR + CSR Hybrid | Marketing site runs SSR; dashboard runs CSR — same codebase |
You don't write code. You talk to AI. Here's the loop:
1. Tell the AI what you want
"Add a feature where users can create projects with a name and description"
2. AI writes the code following the spec — schema, API, UI, all wired up
3. You verify it works
make lint && make tsc # if green, the code is correct
make dev # open browser, test it yourself4. Done. Ship it.
The spec ensures AI-generated code is consistent every single time, even across different AI tools.
The spec in .github/copilot-instructions.md works with:
- Claude Code (recommended)
- GitHub Copilot
- Cursor
- Codex / ChatGPT
- Gemini CLI
- Qwen / GLM / any LLM
The intelligence is in the architecture, not the tool.
| Tool | Version | Install |
|---|---|---|
| Docker | 24+ | Required for DB + storage |
| Node.js | 20+ | brew install node or apt |
| pnpm | 10+ | npm install -g pnpm |
Windows (WSL2) — Strongly Recommended
Pure Windows (no WSL) is not supported. Running directly on Windows requires manually porting every shell command, Makefile, and Docker volume path — it is unnecessarily complex and fragile.
WSL2 is strongly recommended. It gives you a real Linux environment inside Windows, works seamlessly with Docker Desktop, and is fully compatible with AI coding tools (Claude Code, Cursor, Copilot, etc.) — making the entire workflow smooth and reliable.
# 1. Open PowerShell as Administrator and run:
wsl --install
# This installs WSL2 + Ubuntu by default. Reboot when prompted.If you already have WSL1, upgrade it:
wsl --set-default-version 2
wsl --list --verbose # confirm VERSION = 2- Download Docker Desktop for Windows
- During install (or in Settings → General), enable "Use the WSL 2 based engine"
- In Settings → Resources → WSL Integration, enable integration for your Ubuntu distro
# Open Ubuntu from Start Menu (or: wsl in PowerShell)
# Then follow the Linux steps — everything works identically
curl -fsSL https://specc.sh | bashmacOS
brew install node
npm install -g pnpm
# Install Docker Desktop from https://docs.docker.com/desktop/install/mac-install/Linux (Ubuntu / Debian)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g pnpm
# Install Docker: https://docs.docker.com/engine/install/ubuntu/| Command | What it does |
|---|---|
make init |
First-time setup |
make dev |
Start dev environment |
make build |
Build for production |
make lint |
Check code quality |
make tsc |
Check types |
make prod |
Build + start production stack |
cp packages/server/.env.example packages/server/.env
cp packages/web/.env.example packages/web/.env| Variable | Where | Description |
|---|---|---|
DATABASE_URL |
server/.env |
PostgreSQL connection |
STORAGE_ENDPOINT |
server/.env |
S3 / MinIO endpoint |
VITE_TRPC_URL |
web/.env |
API endpoint |
VITE_STORAGE_PUBLIC_URL |
web/.env |
Public file URL prefix |
| Layer | Technology |
|---|---|
| Backend | Hono + tRPC v11 |
| Database | PostgreSQL 18 + Prisma ORM |
| Frontend (Web) | React 19 + Vite 8 — SSR + CSR hybrid |
| Mini-Program | Taro + React — WeChat native |
| Styling | TailwindCSS 4 |
| Validation | Zod v4 |
| Storage | MinIO (S3-compatible) |
| Cache | Redis 7 |
| Lint | Biome |
MIT