Engineering Standards
Lightweight development practices and standards for software projects.
To adopt them in a new or existing project, start with QUICKSTART.md: the steps in order, with snippets to copy and a prompt that has a Claude Code session carry them out.
Purpose
This repository defines engineering standards for building software. The standards are intentionally lightweight to support early-stage agile development while providing enough structure to maintain quality and enable effective collaboration—both human-to-human and human-to-AI.
Repository Structure
Process Standards
Defines how and when to create documentation:
- Repository structure (
docs/ directory organization)
- File naming conventions
- Documentation types (product specs, technical designs, ADRs)
- Best practices for spec-driven development
- Markdown formatting and diagram tools
Key principle: Documentation is the source of truth. Write specs before code, keep them current, focus on decisions and context rather than implementation details.
Defines the process for product/business-driven feature work from concept to production:
- Product Concept - Articulate the problem and opportunity
- Product Requirements & UI Design - Define what to build
- Project Planning & Sequencing - Break work into implementable increments
- Technical Design & Architecture - Specify how to implement
- Implementation - Write code that implements the spec
- Validation & Iteration - Verify and improve
Key principle: Intent → Spec → Plan → Execute → Validate. Small scoped changes, continuous validation, spec-driven development.
Detailed guidance for Phase 3 of the feature development workflow:
- Story point estimation - Fibonacci scale (1-13), baseline 2 points = ~1 day
- Task breakdown - Decomposition strategies and patterns
- Sequencing and dependencies - Critical path, parallel tracks, dependency mapping
- Risk identification - Common risks and mitigation strategies
Project management as a discipline deserves its own detailed standard while keeping the feature development workflow lightweight.
Engineering-driven work separate from product features:
- Bug fixes - Classification, triage, investigation documentation
- Technical debt - Proposals, justification, prioritization
- Infrastructure and tooling - Specifications, operational requirements
- Security fixes - Handling by severity, documentation requirements
Key distinction: Feature work is driven by product/business stakeholders; technical work is driven by engineering directives and engineers directly.
Branch management and version control workflow:
- GitHub Flow - Simple branch-based workflow with
main + feature branches
- Issue-based branching - Use GitHub's auto-generated branch names from issues
- Commit conventions - Clear, conventional commit message format
- Pull request guidelines - Size, description, and review practices
- Release versioning - Semantic versioning and tagging
Key principle: main is always deployable. All work happens in issue-based feature branches merged via pull requests.
How to organize issues, track epics, and manage multi-issue initiatives in GitHub:
- Three-tier hierarchy - Milestones (initiatives), epics (feature themes), implementation issues
- Epic structure - Native GitHub sub-issues with automatic progress tracking
- Label strategy - One table defining every label, tagged by the scale and toolchain it applies to
- Epic lifecycle - Creating, amending, closing, and cancelling epics
- Cross-epic dependencies - Documenting and handling blocking relationships
Key principle: Use GitHub's native features (sub-issues, labels, milestones) for lightweight, scalable issue organization without external tools.
What every repository needs besides its code, public or private:
- Triggers - Each item applies when the repository is public, takes outside contributions, or ships code others use, and is required or recommended under that trigger
- License, SECURITY.md, CONTRIBUTING.md, templates - What each must contain, including private vulnerability reporting and DCO as an option
- Leak gate - gitleaks with committed credential and shape rules in CI, and private value rules that run only on a maintainer's machine
- Going public - Sweeping history before a private repository changes visibility
Key principle: Start from the smallest required set, and say plainly what each check cannot see.
Operational reference for adopting compound-engineering (CE) as the canonical realization of Layers 2–5 of the six-layer AI architecture. Covers artifact path mapping, ticket-tracking modes (team-scale and solo + AI), branch-naming reconciliation, AI-review discipline, and the CE skill ↔ standards doc cross-reference. Self-contained — usable by any adopter without rmorison context.
Key principle: The architecture is the abstraction; CE is one canonical realization. Vendor-neutral baselines remain in place for projects that don't adopt the plugin.
An opt-in operating model for one human directing several AI agent sessions: the operator signs off and merges, a lead coordinates, and one worker runs each ticket. Covers roles, the sprint loop, traffic between parallel tickets, a worker handoff template, the lead's Done-gate checklist, operator interaction (quiet mode), and how to adopt or decline it.
To start one, install the agent-team plugin and run its start-team skill, or start the lead by hand: see the Quickstart.
Conversation logs documenting the development and evolution of these standards through AI agent collaboration.
What's included:
- Decision-making processes and rationale
- Design alternatives considered
- Lessons learned during development
- Questions addressed and resolved
These transcripts provide historical context and reasoning behind the standards, useful for understanding why certain approaches were chosen and how to adapt them appropriately.
AI / Claude Code Integration
Defines how AI tooling integrates with software engineering workflows. The architecture is the abstraction; specific toolkits — most concretely compound-engineering (CE) for Claude Code — fill the layers as canonical realizations. Vendor-neutral baselines live in this repository for projects that don't adopt a specific toolkit.
| # | Layer | Principle | Vendor-neutral baseline |
|---|
| 1 | Rules | Persistence — always-loaded session context | ai/claude-code/rules/ (this repo); templates/CLAUDE.md (an adopter's) |
| 2 | Workflow Skills | Composability — multi-step orchestrators | templates/.claude/skills/ |
| 3 | Persona Agents | Perspective — multiple expertises | templates/.claude/agents/ |
| 4 | References | Progressivity — context grows with workflow depth | (none yet) |
| 5 | Compound / Learnings | Compounding — institutional knowledge accumulates | (none yet) |
| 6 | Hooks | Determinism — non-AI enforcement at zero context cost | templates/.claude/hooks/ |
CE fills Layers 2–5. What it puts in each slot — skills, personas, reference subtrees, artifact paths — lives in process/compound-engineering-integration.md, which tracks it against a stated CE version. Layers 1 and 6 stay owned by your project: Layer 1 as its root CLAUDE.md, Layer 6 as its .claude/hooks/.
Key principle: Context is expensive — only load what's needed, when it's needed. The six layers each specialize this principle for a different context-cost slot.
For the architectural decision and full layer descriptions, see ADR-0001 and ai/claude-code/README.md. For CE adoption operational details, see process/compound-engineering-integration.md.
Starter kit for adopting these standards in new projects with Claude Code:
- Copy
templates/.claude/ into your project root as .claude/ — provides Layers 2 (skills), 3 (agents), 6 (hooks) baselines plus configuration.
- Copy
templates/CLAUDE.md to your project root and fill in the placeholder sections — this is the project's Layer 1 (rules). The ai/claude-code/rules/ baseline in the table above is this repository's own Layer 1 and is not copied; draw on it when filling CLAUDE.md in.
- If you adopt compound-engineering, install the plugin and consult
process/compound-engineering-integration.md for the operational details. CE specializes Layers 2, 3, 4, and 5 with deep implementations; Layers 1 and 6 stay owned by your project — Layer 1 as its root CLAUDE.md, Layer 6 as its .claude/hooks/.
- Customize hooks, skills, agents, and settings for your project's architecture.
The vendor-neutral skills reference the canonical standards via URL, so they stay in sync without duplication.
Philosophy
Lightweight, Not Heavyweight
These standards prioritize working software over process compliance. Use judgment:
- For trivial changes: A good PR description may be sufficient
- For experiments: A brief experiment doc beats formal specs
- For major features: Follow the full workflow to avoid rework
Spec-Driven Development
Write specifications before code. Specs:
- Clarify intent and surface questions early
- Enable AI-assisted development with clear context
- Serve as contracts for testing and validation
- Document decisions for future reference
The spec is source of truth. Code implements the spec.
Agile and Iterative
Ship small increments frequently. Validate early. Learn from users. Iterate based on feedback. Don't over-engineer for hypothetical future requirements.
AI-Native Workflow
Modern development increasingly involves AI coding assistants. These standards work well with AI:
- Clear specs give AI better context
- Small scopes reduce AI errors
- Validation catches AI-generated bugs
- Iteration is cheaper with AI assistance
When to Deviate
These are standards, not laws. Deviate when:
- The standard adds no value for the situation
- Time constraints require faster iteration
- You have a better approach that you'll document
When deviating intentionally, document why in the commit message or PR description.
Maintenance
These standards will evolve:
- Propose changes via pull requests
- Update based on lessons learned
- Keep lightweight—resist adding complexity
- Review quarterly for relevance
Status
Draft - These standards are in active development and subject to revision based on practical experience.
Questions or Feedback
Open an issue or submit a PR to discuss improvements to these standards.
