majiayu000 Governance Skill
Enforces engineering standards and code quality policies during development.
Standards Document: docs/architecture/standards.md Governance Documentation: docs/governance/ Audit Script:
npm run audit:standards
Quick Start (First-Time Setup)
1. Run Setup Check
# Comprehensive governance setup verification
node .claude/skills/governance/scripts/governance-check.mjs
This checks CLAUDE.md, standards.md, audit script, ADRs, and pre-commit hooks with actionable fix instructions.
2. Understand the Two-Document Model
| Document | Purpose | Update Frequency |
|---|---|---|
| CLAUDE.md | AI operational context (commands, URLs, quick-ref) | Frequent |
| standards.md | Engineering policy (authoritative) | Infrequent |
Rule: CLAUDE.md defers to standards.md for authoritative definitions.
3. Common Operations
# Check standards compliance
npm run audit:standards
# Typecheck before commit
npm run typecheck && npm run lint && npm run test
# View pre-commit checklist
cat docs/architecture/standards.md | grep -A20 "Pre-Commit Checklist"
When This Skill Activates
During Code Review
When reviewing code or discussing PRs, automatically check:
- File length compliance (max 500 lines per file)
- Naming conventions match project standards
- Test coverage exists for new code
- No forbidden patterns (
anytypes, hardcoded secrets)
Before Commits
When helping prepare commits, remind about:
- Pre-commit checklist (typecheck, lint, test)
- Standards audit (
npm run audit:standards) - Commit message format (conventional commits)
Core Standards Quick Reference
Full reference: docs/architecture/standards.md
Code Quality (§1)
| Standard | Requirement | Check |
|---|---|---|
| TypeScript | Strict mode enabled | npm run typecheck |
No any types |
Use unknown for external data |
Audit script |
| Max file length | 500 lines | Audit script |
| JSDoc | Required for public APIs | Audit script |
Naming Conventions (§1.2)
| Element | Convention | Example |
|---|---|---|
| Components | PascalCase | Button.tsx, UserCard.astro |
| Utilities | camelCase | userService.ts |
| Variables | camelCase | getUserById() |
| Constants | SCREAMING_SNAKE | const MAX_RETRIES = 3 |
| DB columns | snake_case | user_id, created_at |
| CSS classes | kebab-case | nav-sidebar |
Testing (§2)
| Layer | Target | Framework (example) |
|---|---|---|
| Unit tests | 90-100% | Vitest, Jest, pytest |
| API routes | 90-100% | Testing framework + supertest |
| E2E critical paths | 100% | Playwright, Cypress |
Workflow (§3)
- Branching:
feature/,fix/,chore/,docs/prefixes - Commits:
<type>(scope): <description> - Review: All code requires approval before merge
Compliance Check
Run the standards audit before committing:
npm run audit:standards
This checks:
- TypeScript strict mode
- No
anytypes in source - File length limits (500 lines)
- JSDoc on exported functions
- Test files exist
- Feature flags module exists
- CLAUDE.md exists
- ADR directory exists
- Pre-commit hooks configured
Handling Failures
| Failure | Resolution |
|---|---|
| File too long | Split into modules (document decision in ADR if significant) |
| Missing JSDoc | Add documentation to exported functions |
any type found |
Replace with proper type or unknown |
| Missing tests | Add test coverage for new code |
Anti-Patterns vs Correct Patterns
Code Quality
| Anti-Pattern | Correct Pattern | Why |
|---|---|---|
❌ any type |
✅ unknown for external data |
Type safety at runtime boundaries |
| ❌ 600+ line files | ✅ Split at 500 lines | Maintainability, easier review |
❌ console.log in production |
✅ Proper logging or remove | Security, performance |
| ❌ Hardcoded secrets | ✅ Environment variables | Security best practice |
Documentation
| Anti-Pattern | Correct Pattern | Why |
|---|---|---|
| ❌ Duplicating policy in CLAUDE.md | ✅ Cross-reference standards.md | Single source of truth |
| ❌ No JSDoc on public functions | ✅ JSDoc with @param, @returns | API discoverability |
| ❌ Inline comments explaining "what" | ✅ Comments explaining "why" | Code should be self-documenting |
Workflow
| Anti-Pattern | Correct Pattern | Why |
|---|---|---|
| ❌ Committing directly to main | ✅ Feature branches with PR | Code review, CI checks |
❌ git push --force to main |
✅ Never force-push protected branches | History integrity |
| ❌ Skipping audit:standards | ✅ Run before every commit | Catch issues early |
| ❌ Merge without review | ✅ Require approval | Quality gate |
Testing
| Anti-Pattern | Correct Pattern | Why |
|---|---|---|
| ❌ Tests after code | ✅ TDD or tests alongside | Better design, coverage |
| ❌ Mocking internal modules | ✅ Mock only external services | Test real behavior |
| ❌ Ignoring flaky tests | ✅ Fix or quarantine immediately | CI reliability |
Pre-Commit Checklist
Before every commit:
[ ] npm run typecheck # TypeScript compiles
[ ] npm run lint # Linter passes
[ ] npm run test # Tests pass
[ ] npm run audit:standards # Standards compliance
[ ] No console.log statements (use proper logging)
[ ] No hardcoded secrets
[ ] Meaningful commit message
PR Review Checklist
When reviewing or preparing PRs:
| Category | Criteria |
|---|---|
| Correctness | Does it work? Edge cases handled? |
| Security | No secrets, injection vulnerabilities, or auth bypasses |
| Performance | No N+1 queries, unnecessary re-renders, or memory leaks |
| Style | Matches project conventions, readable, maintainable |
| Testing | Tests exist for new functionality |
| Scope | No unrelated changes, minimal footprint |
PR Description Template
## Summary
[What this PR does in 1-2 sentences]
## Ticket
[PROJECT-XXX](link)
## Changes
- Change 1
- Change 2
## Testing
- [ ] Unit tests added/updated
- [ ] Tested in deploy preview
- [ ] Edge cases considered
## Screenshots (if UI changes)
[Before/After screenshots]
Two-Document Model
This project uses a two-document governance model:
| Document | Purpose | Location |
|---|---|---|
| CLAUDE.md | AI operational quick-reference | Project root |
| standards.md | Engineering policy (authoritative) | docs/architecture/ |
- CLAUDE.md is optimized for token efficiency — concise commands and context
- standards.md is optimized for human comprehension — rationale and justifications
Rule: CLAUDE.md defers to standards.md for authoritative definitions using section references (§1.3).
Using This Skill in Other Projects
To replicate this governance model:
Copy the skill:
cp -r .claude/skills/governance /path/to/new-project/.claude/skills/Copy governance docs:
cp -r docs/governance /path/to/new-project/docs/Create standards.md using the template at docs/governance/guardrails-template.md
Create audit script using scripts/audit-standards.mjs as a starting point
Add npm script:
"audit:standards": "node scripts/audit-standards.mjs"Update CLAUDE.md to cross-reference standards.md
Related Documents
- Engineering Standards — Authoritative policy
- Guardrails Instructions — How the model works
- Guardrails Template — For new projects
- ADR Index — Architecture decisions
Last updated: December 2025 Project-level governance enforcement for Claude Code