DevFlow Constitution Quick Reference

Purpose

Provide quick summaries of all 10 Constitutional Articles with links to full Constitution document. This skill does NOT duplicate the complete Constitution text.

Full Constitution: .claude/constitution/project-constitution.md v2.0.0

Constitution Overview

Version: v2.0.0 Effective Date: 2025-01-10 Authority: Supreme Priority, Inviolable, Persistent, Universal Scope: All requirements, all stages, all agents

Article I: Quality First (质量至上)

Summary

Quality is the non-negotiable baseline.

Key Rules

• I.1: NO PARTIAL IMPLEMENTATION (no TODO/FIXME placeholders)
• I.2: Test coverage ≥80%
• I.3: No "simplified for now" excuses
• I.4: Must pass type checking, linting, security scanning, build verification

Enforcement

• Real-time: constitution-guardian guardrail (blocks TODOs/FIXMEs)
• Batch: validate-constitution.sh --type all
• Pre-push: pre-push-guard.sh

Example Violations

❌ "TODO later: Add email verification"
❌ "// Simplified for now, will complete in v2"
❌ "defer to v2"

For Details: See Constitution Article I

---

Article II: Architectural Consistency (架构一致性)

Summary

Maintain codebase uniformity and predictability.

Key Rules

• II.1: No code duplication (search existing codebase first)
• II.2: Consistent naming (follow existing patterns)
• II.3: Anti-over-engineering (no BaseController, AbstractService)
• II.4: Single responsibility (≤500 lines per file)

Enforcement

• Phase -1 Gates: planner agent checks before EPIC generation
• Code review: code-reviewer agent

Example Violations

❌ class BaseController {}       // Over-abstraction
❌ function helperManager() {}   // Vague naming
❌ 800-line file                 // Exceeds limit

For Details: See Constitution Article II

---

Article III: Security First (安全优先)

Summary

Security is foundational, not an afterthought.

Key Rules

• III.1: NO HARDCODED SECRETS (use env variables)
• III.2: All inputs must be validated BEFORE processing
• III.3: Principle of least privilege (deny by default)
• III.4: Secure by default (HTTPS, CORS whitelist, auth required)

Enforcement

• Real-time: constitution-guardian guardrail (blocks hardcoded secrets)
• Pre-push: pre-push-guard.sh scans for secret patterns
• QA: security-reviewer agent

Example Violations

❌ const API_KEY = "sk-abc123..."    // Hardcoded
❌ const PASSWORD = "admin123"       // Hardcoded

For Details: See Constitution Article III

---

Article IV: Performance Accountability (性能责任)

Summary

Performance is user experience; proactive optimization required.

Key Rules

• IV.1: No resource leaks (always close connections)
• IV.2: Algorithm efficiency (avoid O(n²) when O(n) exists)
• IV.3: Lazy loading (pagination for large datasets)
• IV.4: Intelligent caching (with TTL and invalidation)

Enforcement

• QA: qa-tester agent includes performance profiling
• Code review: code-reviewer agent checks resource management

Example Violations

❌ loadAllUsers()                    // Loads 1M users into memory
❌ nested loops over same dataset    // O(n²)
❌ no connection.close()             // Resource leak

For Details: See Constitution Article IV

---

Article V: Maintainability (可维护性)

Summary

Code must be understandable, modifiable, and extensible.

Key Rules

• V.1: No dead code (delete unused imports, commented code)
• V.2: Separation of concerns (models, services, controllers, views)
• V.3: Documentation mandate (complex algorithms, business logic)
• V.4: File size limits (≤500 lines per file, ≤50 lines per function)

Enforcement

• Linting: ESLint, Pylint rules
• Code review: code-reviewer agent

Example Violations

❌ // Commented-out code block    // Dead code
❌ Unused import statements         // Dead code
❌ 800-line function               // Exceeds limit

For Details: See Constitution Article V

---

Article VI: Test-First Development (测试优先开发)

Summary

Tests define behavior; implementation makes tests pass.

Key Rules

• VI.1: TDD mandate (write tests FIRST, tests MUST fail initially)
• VI.2: Test independence (each test runs in isolation)
• VI.3: Meaningful tests (no assert True, test actual behavior)

Enforcement

• Real-time: devflow-tdd-enforcer guardrail (blocks TDD violations)
• TASKS.md: TEST VERIFICATION CHECKPOINT between Phase 2 and Phase 3
• planner agent: Generates TASKS.md with TDD order

TDD Sequence

Phase 2: Write Tests FIRST ⚠️
  → All tests MUST fail initially
  → TEST VERIFICATION CHECKPOINT

Phase 3: Write Implementation
  → Goal: Make tests pass

For Details: See Constitution Article VI

---

Article VII: Simplicity Gate (简单性闸门)

Summary

Default to simplicity; complexity requires justification.

Key Rules (Phase -1 Gates)

• VII.1: Maximum project count ≤3 simultaneously
• VII.2: Minimal dependencies (use standard library when possible)
• VII.3: Vertical slice first (full feature before next feature)
• VII.4: Direct framework usage (avoid custom abstractions)

Enforcement

• Phase -1 Gates: planner agent enforces BEFORE generating EPIC
• EPIC.md: Contains "Phase -1 Simplicity Gate" check section

Example Violations

❌ 5 projects in scope                    # Exceeds limit
❌ Adding new framework for simple task   # Over-dependency
❌ Custom ORM wrapper                     # Unnecessary abstraction

For Details: See Constitution Article VII

---

Article VIII: Anti-Abstraction (反抽象化)

Summary

Prefer concrete code over abstractions until three+ use cases proven.

Key Rules (Phase -1 Gates)

• VIII.1: No premature abstraction (Rule of Three)
• VIII.2: No generic layers (no GenericService)
• VIII.3: Direct framework usage (Express, FastAPI, Flask)
• VIII.4: Inline before extract (copy-paste OK until 3rd repetition)

Enforcement

• Phase -1 Gates: planner agent enforces BEFORE generating EPIC
• EPIC.md: Contains "Phase -1 Anti-Abstraction Gate" check section

Example Violations

❌ class BaseController {}              // Premature abstraction
❌ GenericRepository<T>                 // Generic layer
❌ Custom framework wrapper             // Over-abstraction

For Details: See Constitution Article VIII

---

Article IX: Integration-First Testing (集成优先测试)

Summary

Test contracts/integrations before internal logic.

Key Rules (Phase -1 Gates)

• IX.1: Contract tests first (API contracts, GraphQL schemas)
• IX.2: Integration tests before unit tests (test boundaries first)
• IX.3: Test external dependencies (database, APIs, queues)
• IX.4: E2E critical paths (happy path + error path)

Enforcement

• Phase -1 Gates: planner agent enforces BEFORE generating EPIC
• TASKS.md Phase 2: Lists contract/integration tests FIRST
• TEST VERIFICATION CHECKPOINT: Ensures Phase 2 tests run before Phase 3

Test Order

1. Contract tests (API contracts, GraphQL)
2. Integration tests (DB, external APIs)
3. E2E tests (critical user paths)
4. Unit tests (internal logic)

For Details: See Constitution Article IX

---

Article X: Requirement Boundary (需求边界)

Summary

Prevent scope creep; enforce strict requirement boundaries.

Key Rules

• X.1: One REQ-ID, one bounded context (no "also add X")
• X.2: No feature expansion during implementation
• X.3: Separate REQ-IDs for separate concerns
• X.4: Explicit scope documentation in PRD.md

Enforcement

• PRD generation: prd-writer agent enforces Anti-Expansion mandate
• Scope validation: validate-scope-boundary.sh
• Code review: code-reviewer agent checks for scope violations

Example Violations

❌ PRD.md: "User Registration (also add social login)"    # Scope creep
❌ Adding unplanned features during /flow-dev             # Feature expansion

For Details: See Constitution Article X

---

Phase -1 Gates

Executed by: planner agent BEFORE generating EPIC and TASKS

Gate 1: Simplicity Check (Article VII)

• Project count ≤3
• Minimal dependencies
• Vertical slice approach
• Direct framework usage

Gate 2: Anti-Abstraction Check (Article VIII)

• No premature abstractions
• No generic layers
• Inline before extract
• Direct framework calls

Gate 3: Integration-First Check (Article IX)

• Contract tests listed first
• Integration tests before unit tests
• External dependency tests included
• E2E critical paths covered

Documented in: EPIC.md contains "Phase -1 Gates" check section

For Details: See planner agent Phase -1 Gates Enforcement Sequence

---

Enforcement Summary

Article	Real-time Guardrail	Phase Gate	Batch Validation	Pre-push
I	constitution-guardian	prd/tech/epic Exit	validate-constitution.sh	✓
II	—	Phase -1 (planner)	validate-constitution.sh	—
III	constitution-guardian	—	validate-constitution.sh	✓
IV	—	—	validate-constitution.sh (QA)	—
V	—	—	Linting + code review	—
VI	devflow-tdd-enforcer	TEST VERIFICATION	validate-constitution.sh	—
VII	—	Phase -1 (planner)	validate-constitution.sh	—
VIII	—	Phase -1 (planner)	validate-constitution.sh	—
IX	—	Phase -1 (planner)	validate-constitution.sh	—
X	—	PRD generation	validate-scope-boundary.sh	—

---

Quick Lookup by Scenario

Scenario: "Can I add TODO for later?"

Answer: ❌ NO (Article I.1 - No Partial Implementation) Guardrail: constitution-guardian blocks save Alternative: Complete implementation now, or remove from scope

Scenario: "Should I create BaseController?"

Answer: ❌ NO (Article II.3, VIII.2 - Anti-Abstraction) Phase Gate: Phase -1 Gates block EPIC generation Alternative: Use framework directly (Express, FastAPI)

Scenario: "Can I hardcode API_KEY for testing?"

Answer: ❌ NO (Article III.1 - No Hardcoded Secrets) Guardrail: constitution-guardian blocks save Alternative: Use .env file with dotenv library

Scenario: "Should I write implementation first?"

Answer: ❌ NO (Article VI.1 - TDD Mandate) Guardrail: devflow-tdd-enforcer blocks TASKS.md edit Sequence: Write failing test FIRST, then implementation

Scenario: "Can I add social login to user registration?"

Answer: ❌ NO (Article X.1 - Requirement Boundary) Enforcement: prd-writer agent Anti-Expansion mandate Alternative: Create separate REQ-ID for social login

---

Design Principle

This skill does NOT contain:

• ❌ Complete Constitution text (that's in project-constitution.md)
• ❌ Detailed Article explanations (that's in full Constitution)
• ❌ Implementation guidelines (those are in agent files)

This skill ONLY contains:

• ✅ Article summaries (quick reference)
• ✅ Key rules and examples
• ✅ Enforcement mechanisms
• ✅ Links to full Constitution document
• ✅ Quick lookup by scenario

Rationale: Avoid duplication ("不重不漏" principle). Constitution document owns full text, this skill owns quick reference and routing.