claude-ground

A minimal rule system for Claude Code. Gives Claude the structural discipline it lacks by default — phase tracking, decision logging, honest pushback, debug discipline, and language-specific best practices.

The problem

Claude Code is capable. But left to its own defaults it tends to:

• Lose track of the original plan mid-implementation
• Silently simplify or pivot when blocked, without asking
• Agree with you when it should push back
• Brute-force the same failed approach instead of stopping to think
• Modify existing code without understanding it first
• Skip tests or write superficial ones
• Use inline styles, hardcoded colors, and generic AI aesthetics

These aren't model failures — they're defaults that go unchallenged without explicit rules.

What this does

rules/common/ — Always active, every project:

rules/[language]/ — Language-specific best practices:

All rules use MUST / SHOULD / RECOMMENDED severity levels so Claude knows what is a hard rule vs a best practice.

templates/ — Starting point for new projects:

• CLAUDE.md — Project context file. Tech stack, architecture, active rules.
• DECISIONS.md — Empty decisions log, ready to fill.
• phases/PHASE-01.md — First phase template.

Install

Two things get installed — they go to different places:

Rules are always global. Templates are always local to whatever directory you run the command from.

Step 1 — Install rules (once)

git clone https://github.com/akinalpfdn/claude-ground
cd claude-ground
node install.js                    # interactive — pick languages
node install.js go typescript      # non-interactive — specify languages directly

This installs common rules + your chosen language rules to ~/.claude/rules/. Done once, works everywhere.

No dependencies. Uses only Node.js built-ins — no npm install needed.

Step 2 — Set up a project (per project)

From your project directory:

cd your-project
node /path/to/claude-ground/install.js --templates

This asks if the project has a UI (to enable frontend rules), then creates:

your-project/
├── CLAUDE.md                        ← fill this in
├── DECISIONS.md                     ← log your first stack decision
└── .claude/
    └── phases/
        └── PHASE-01-active.md       ← define your first phase

--templates alone does not reinstall rules — it only creates project files. To combine both (e.g. fresh machine):

node /path/to/claude-ground/install.js --templates go swift

Step 3 — Fill in CLAUDE.md

Open CLAUDE.md and fill in:

• What the project does
• Your tech stack and why
• Uncomment the language rules that apply
• Any project-specific constraints for Claude

Phase workflow

Long implementations use phase files to survive context resets:

.claude/phases/
├── PHASE-01-done.md       ← completed
├── PHASE-02-done.md       ← completed
├── PHASE-03-active.md     ← Claude reads this when context fills
└── PHASE-04-pending.md    ← not started

Each phase file contains: goal, task list, acceptance criteria. No code snippets — phases are goals, not implementations.

Claude checks the active phase file before continuing work. It will not start the next phase without your approval.

Folder structure

claude-ground/
├── install.js
├── rules/
│   ├── common/
│   │   ├── core.md            # phase management, approval gates, honest pushback
│   │   ├── decisions.md       # decision log format and rules
│   │   ├── git.md             # branch strategy, commits, versioning
│   │   ├── testing.md         # test discipline, naming, coverage
│   │   ├── debug.md           # two-attempt rule, structured analysis
│   │   ├── existing-code.md   # read before touch, pattern respect
│   │   └── frontend.md        # theme-first, intentional design (UI only)
│   ├── go/
│   │   └── go.md
│   ├── swift/
│   │   └── swift.md
│   ├── typescript/
│   │   └── typescript.md
│   ├── kotlin/
│   │   └── kotlin.md
│   ├── flutter/
│   │   └── flutter.md
│   ├── rust/
│   │   └── rust.md
│   ├── python/
│   │   └── python.md
│   ├── dotnet/
│   │   └── dotnet.md
│   └── spring/
│       └── spring.md
└── templates/
    ├── CLAUDE.md
    ├── DECISIONS.md
    └── phases/
        └── PHASE-01.md

Contributing

Rules should be:

• Specific enough to change behavior, not just remind Claude of good practices
• Language-idiomatic — written from the perspective of someone who knows the ecosystem well
• Free of code snippets that Claude would write anyway
• Tagged with severity: MUST (hard rule), SHOULD (best practice), RECOMMENDED (nice to have)

New language rules, corrections, and improvements are welcome.