English | 简体中文
AI writes code fast. This skill makes it write code right.
ten-dev-rules is an agent skill for Claude Code that transforms 10 engineering rules into active decision gates — the AI must scope before coding, freeze contracts before building, verify before shipping. No ceremony, just discipline.
AI coding assistants are powerful but undisciplined. Without guardrails, they:
- Start coding before understanding the scope
- Modify shared interfaces without freezing contracts
- Skip failure path design and ship happy-path-only code
- Repeat the same mistakes across different projects
ten-dev-rules fixes this by making the AI enforce engineering discipline on itself — and learn from your mistakes across projects.
| Command | Type | What It Does |
|---|---|---|
/10dev |
Entry | Onboarding, project scan, status dashboard |
/10plan |
Mode | Scope boundary -> freeze contracts -> sequence deps -> stage work -> WATCH LIST |
/10exec |
Mode | Detect env -> implement -> run tests/lint -> stage code review -> atomic commit |
/10review |
Mode | 10-rule audit + self-check gate + deep code review -> SHIP / BLOCK verdict |
/10distill |
Mode | Extract principles -> update developer profile -> cross-project pattern detection |
/10docs |
Mode | Auto-fix stale docs -> delete duplicates -> generate TOCs -> archive -> sync vault |
/10profile |
Tool | View/manage developer blind spots, preferences, and progress |
All modes also trigger via natural language: "plan this feature", "review this PR", "what did we learn", etc.
New to 10devrules? Start with /10dev — it guides you through setup and launches your first mode.
| # | Rule | What the Agent Does |
|---|---|---|
| 1 | Set the boundary | Defines solves/defers/removed. Hook flags out-of-scope edits. |
| 2 | Freeze the contract | Stabilizes interfaces before consumers are built. Writes .10dev/contract.md. |
| 3 | Sequence by dependency | Builds foundations first. Flags circular deps for resolution. |
| 4 | Stage the work | Splits into phases with entry/exit conditions and predicted file lists. |
| 5 | Isolate new complexity | New logic in new files. Shared core edits require justification. |
| 6 | Build the review loop | Every stage: implement -> review -> fix -> re-verify. |
| 7 | Design failure paths | Enumerates unhappy paths per stage. Zero failure paths = hard stop. |
| 8 | Compress documentation | Living specs, not history. Minimum docs that restore context. |
| 9 | Verify reality | Must state verified/skipped/risk before marking done. |
| 10 | Distill reusable principles | Extracts patterns using action verbs: scope, freeze, isolate, verify. |
Each rule is a gate, not a suggestion. The agent enforces them at specific workflow points.
# Clone into your Claude Code skills directory
git clone https://github.com/fitclaw/10devrules.git ~/.claude/skills/ten-dev-rules
# Register per-mode slash commands
cd ~/.claude/skills
for cmd in 10dev 10plan 10exec 10review 10distill 10docs 10profile; do
ln -sf ten-dev-rules/skills/$cmd $cmd
done
# Done. Type /10dev to get started.You: /10dev
Agent: [Detects new project, scans environment, offers CLAUDE.md routing setup]
-> Environment ready. What would you like to do first?
You: /10plan Add user authentication with OAuth
Agent: [Sets boundary, freezes contracts, sequences deps, stages work, shows WATCH LIST]
-> Structured plan with 4 stages, frozen contracts, failure paths, and profile warnings
You: /10exec
Agent: [Detects test framework, implements each stage, runs tests+lint, auto-reviews code]
-> Stage 1 complete. Tests: 6/6. Stage review: R5 PASS, R7 PASS, R9 PASS. Verdict: CONTINUE
You: /10review
Agent: [10-rule audit + self-check gate + deep code review per file]
-> SHIP_WITH_CONCERNS: [P2] check-boundary.sh:42 — realpath not available on macOS
You: /10distill
Agent: [Extracts patterns, compares against developer profile]
-> 2 principles extracted. Profile updated: "Skips failure paths" frequency 2->3.
You: /10profile
Agent: -> 3 blind spots tracked (1 HIGH, 2 MEDIUM). Last healed: "Assumes platform behavior".
You: /10docs
Agent: [Scans all docs, fixes drift, builds cleanup plan]
-> UPDATED: 2 broken links fixed, 1 missing doc created. DELETE 3, TOC 2, ARCHIVE 1. Apply? [Y/n]
10devrules learns from your mistakes across projects.
L0: Project lessons (lessons.md) -> what we learned THIS project
L1: Developer blind spots (profile) -> recurring patterns across projects
L2: Universal principles -> abstracted, project-independent
The profile lives at ~/.10dev/developer-profile.md (global). When you run /10plan, it reads your profile and generates a WATCH LIST — proactive warnings based on your known blind spots. When you run /10distill, it compares new lessons against your profile and proposes updates.
## WATCH LIST (from developer profile)
! HIGH: Assumes platform behavior
Trigger: Developing plugins/extensions for a host platform
Defense: Add task — "Verify platform's extension discovery mechanism"
- [ ] Acknowledged: Assumes platform behavior
MEDIUM: Skips failure path design
Trigger: Feature development enters "excitement" phase
Defense: Rule 7 gate — enumerate unhappy paths per stage
Features:
- Keyword-based matching with agent judgment fallback
- Safe write protocol (atomic mv + .bak backup) for concurrent session protection
- Blind spot healing — auto-propose severity downgrade after 6 months quiet
- Distill diff — see what changed in your profile after each /10distill
- Profile export — anonymized markdown for sharing
Automated document governance (/10docs). Completely rewritten as a single-command pipeline: SCAN → UPDATE → ORGANIZE → EXECUTE → VERIFY. The UPDATE phase auto-fixes broken links, documents undocumented directories, and updates stale references before cleanup begins. One confirmation applies all structural changes.
Documentation drift detection. New bin/doc-drift-check.sh finds broken pointers, undocumented source directories, stale CLAUDE.md references, README version drift, missing standard docs, and code that changed without doc updates.
Single Source of Truth enforcement. New bin/doc-soot-check.sh detects duplicate definitions across markdown files with an authority hierarchy for resolution.
Auto-TOC generation. Files >200 lines automatically get a ## 目录 (Table of Contents) via bin/doc-toc-gen.sh. AI reads the TOC to locate sections by line number.
AI Friendliness score. /10docs audit reports a 0-5 score: CLAUDE.md size, duplication, TOC coverage, archive leaks, and context sufficiency.
Real code review in /10review (self-check gate + deep review). Environment-aware /10exec (auto-detects test frameworks). Stage-level code review. Shared tooling (detect-root.sh, detect-env.sh). Boundary guard improvements.
10devrules enforces 8 behavioral rules on the AI agent, active in every mode:
- Think before acting — read existing files before writing code
- Concise output, thorough reasoning
- Prefer editing over rewriting whole files
- Do not re-read files already in context
- Test before declaring done
- No sycophantic openers or closing fluff
- Keep solutions simple and direct
- User instructions always override skill instructions
These are injected into your project's CLAUDE.md during /10dev setup, so they apply to every session — even outside 10dev modes.
v2.5 uses a router-layer architecture with per-mode skill wrappers, real code review, environment-aware execution, and automated document governance.
SKILL.md (router) docs/ (mode logic) skills/ (slash commands)
+-----------------+ +--------------------+ +--------------------+
| Rules table | | 10plan.md | | 10dev/ (entry) |
| Mode router |------>| 10exec.md | | 10plan/ 10exec/ |
| Output templates| | 10review.md | | 10review/ 10distill|
| Anti-patterns | | 10distill.md | | 10docs/ 10profile/ |
| State files | | 10docs.md | +--------------------+
| Tool commands | | 10dev.md | bin/ (shared scripts)
+-----------------+ | state-files.md | +--------------------+
+--------------------+ | check-boundary.sh |
| doc-health-audit.sh|
| doc-drift-check.sh |
| doc-toc-gen.sh |
| doc-soot-check.sh |
| doc-sync.sh |
+--------------------+
Global state (~/.10dev/):
developer-profile.md L1 blind spots + preferences
universal-principles.md L2 abstracted principles
projects.txt project registry
.onboarded onboarding flag
/10docs runs a full governance pipeline — updates stale docs, then cleans up structure:
| Command | What It Does |
|---|---|
/10docs |
Full pipeline: scan → update drift → organize → execute → verify |
/10docs audit |
Report only — show what would change, no edits |
/10docs sync |
Push state files to Obsidian vault with YAML frontmatter |
The pipeline auto-executes corrections (broken links, missing docs, stale refs) and presents structural changes (delete duplicates, generate TOCs, archive, extract) for one-click approval.
The optional boundary guard hook enforces Rule 1:
- Reads
.10dev/boundary.txt(allowed edit paths) - Checks every
EditandWriteagainst scope - Advisory mode (
ask, notdeny) — you always decide - No boundary file = all edits allowed
- Directory-safe matching (prevents
/srcfrom matching/src-old)
.
+-- SKILL.md # Router layer (v2.5)
+-- docs/
| +-- 10plan.md # PLAN mode (7 phases + WATCH LIST)
| +-- 10exec.md # EXECUTE mode (stage loop + file drift detection)
| +-- 10review.md # REVIEW mode (10-rule audit + profile match)
| +-- 10distill.md # DISTILL mode (4 phases + 3-layer learning)
| +-- 10docs.md # DOCS mode (automated governance pipeline)
| +-- 10dev.md # /10dev orchestrator logic
| +-- state-files.md # Canonical state file schemas
+-- skills/
| +-- 10dev/ # /10dev entry point
| +-- 10plan/ ... 10profile/ # Per-mode slash command wrappers
+-- bin/
| +-- check-boundary.sh # Rule 1 boundary guard
| +-- detect-root.sh # Project root detection (4 fallback strategies)
| +-- detect-env.sh # Test/lint/type tool detection
| +-- doc-health-audit.sh # Document health + governance metrics
| +-- doc-drift-check.sh # Documentation drift from codebase
| +-- doc-toc-gen.sh # TOC check and generation
| +-- doc-soot-check.sh # Single source of truth checker
| +-- doc-sync.sh # Obsidian vault sync engine
+-- CHANGELOG.md / README.md / README.zh-CN.md / CONTRIBUTING.md / SECURITY.md
- Before coding — scope the work, freeze contracts, plan stages
- During coding — isolated stages with review loops and verification
- After coding — audit PRs against 10 rules, extract principles
- Across projects — developer profile carries your lessons forward
- Trivial one-line fixes (the workflow costs more than the change)
- Pure brainstorming (loose exploration is the goal)
- Domains with stricter formal processes that supersede this
Is this only for AI agents? No. Humans and agents both benefit. Agents get explicit workflows. Humans get reduced ambiguity.
Is this tied to a language or framework? No. Language-agnostic and tool-agnostic.
Can I use it without the hook?
Yes. The hook is optional. All rules work as agent instructions in SKILL.md alone.
What dependencies does it need?
Only bash, grep, sed. Standard on macOS and Linux. No npm, no pip, no Docker.
What's the developer profile?
A global file (~/.10dev/developer-profile.md) that tracks your recurring coding blind spots. /10plan reads it to warn you proactively. /10distill updates it. Fully optional — created automatically when you first run /10distill.
Can I modify it for my team? Yes. MIT licensed. Preserve the core rules and adapt everything else.
- No telemetry, analytics, or external services
- No personal data required
- Developer profile is local only (
~/.10dev/) - All examples are generic
- Safe to use in any organization
See CONTRIBUTING.md.
See SECURITY.md.
MIT License. See LICENSE.