rmorison/engineering-standards：面向 Claude Code 的轻量工程标准仓库

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/ - Software process and SDLC standards (workflows, git, planning, documentation)
• code/ - Language and stack-specific code quality standards (Python, Database, Web Application)
• ai/ - AI assistant configuration and Claude Code integration (details)
• templates/ - Project starter kit with Claude Code configuration (.claude/ directory template)
• plugins/ - Claude Code plugins installed from this repository: agent-team starts an agent team in one step
• agent-transcripts/ - Historical development logs
• scripts/ - Documentation checks and the leak gate, run in CI (how to run them locally)
• QUICKSTART.md - How to adopt these standards in a new or existing project, step by step
• SECURITY.md and CONTRIBUTING.md - How to report a vulnerability privately, and how to contribute

Process Standards

Documentation 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.

Feature Development Workflow

Defines the process for product/business-driven feature work from concept to production:

1. Product Concept - Articulate the problem and opportunity
2. Product Requirements & UI Design - Define what to build
3. Project Planning & Sequencing - Break work into implementable increments
4. Technical Design & Architecture - Specify how to implement
5. Implementation - Write code that implements the spec
6. Validation & Iteration - Verify and improve

Key principle: Intent → Spec → Plan → Execute → Validate. Small scoped changes, continuous validation, spec-driven development.

Project Planning Standards

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.

Technical Work Workflow

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.

Git Branching Strategy

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.

Issue Tracking and Epic Organization

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.

Repository Baseline Standards

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.

Compound Engineering Integration

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.

Agent Team Workflow

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.

Agent Transcripts

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

Six-Layer AI Architecture

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.

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.

Project Templates

Starter kit for adopting these standards in new projects with Claude Code:

1. Copy templates/.claude/ into your project root as .claude/ — provides Layers 2 (skills), 3 (agents), 6 (hooks) baselines plus configuration.
2. 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.
3. 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/.
4. 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.