Universal Development Standards

Language: English | 繁體中文 | 简体中文

Version: 3.5.0 Last Updated: 2026-01-15 License: Dual License (CC BY 4.0 + MIT)

What's New in 3.5.0

🧪 = Experimental feature - requires -E flag, will be redesigned in v4.0

Purpose

This repository provides language-agnostic, framework-agnostic, domain-agnostic documentation standards for software projects. These standards ensure consistency, quality, and maintainability across diverse technology stacks.

Quick Start

Install via npm (Recommended)

# Install globally
npm install -g universal-dev-standards

# Initialize your project
uds init

Or use npx (No installation required)

npx universal-dev-standards init

Manual Setup

Copy essential standards to your project:

cp core/anti-hallucination.md your-project/.standards/
cp core/checkin-standards.md your-project/.standards/
cp core/commit-message-guide.md your-project/.standards/

Important: Copying standards alone won't enable AI assistance. You must also reference them in your AI tool's configuration file (e.g., CLAUDE.md, .cursorrules). Use uds init for automatic configuration.

AI Tool Extensions (Optional)

After installing UDS, optionally enable AI-assisted features for your preferred tools:

New in v3.5.0: uds init supports multi-agent Skills installation. Select multiple agents to install Skills simultaneously. Gemini CLI commands are auto-converted to TOML format.

Installation Methods

CLI Tool (Primary Installation)

The CLI tool is the primary way to adopt UDS in your projects.

npm (Recommended)

npm install -g universal-dev-standards
uds init    # Interactive initialization
uds check   # Check adoption status
uds update  # Update to latest version
uds skills  # List installed skills

npx (No installation)

npx universal-dev-standards init

Beta Version (Latest Features)

# Install beta globally
npm install -g universal-dev-standards@beta

# Or use specific version
npm install -g [email protected]

# Or via npx
npx universal-dev-standards@beta init

Note: Beta versions include experimental features like the Methodology System (/methodology, /bdd, /tdd). These features will be redesigned in v4.0. See Feature Availability for details.

Clone and Link (Development)

macOS / Linux:

git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards/cli && npm install && npm link

Windows (PowerShell):

git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards\cli; npm install; npm link

See CLI README for detailed usage, Windows Guide for Windows-specific instructions, and Operation Workflow for project maintenance and development workflow.

AI Tool Configuration

Each AI tool uses a configuration file for project-specific rules. uds init generates these automatically:

Or manually copy from integrations/ directory.

Agent Skills Installation

Agent Skills are interactive commands (/commit, /tdd, /review, etc.) that enhance AI-assisted development. Skills follow the Agent Skills Standard and work across multiple AI tools.

Skills included (15 skills): ai-collaboration-standards, changelog-guide, code-review-assistant, commit-standards, documentation-guide, error-code-guide, git-workflow-guide, logging-guide, project-structure-guide, release-standards, requirement-assistant, spec-driven-dev, tdd-assistant, test-coverage-assistant, testing-guide

Supported Tools

Method 1: Claude Code Plugin Marketplace

For Claude Code users, the Plugin Marketplace offers the easiest installation:

/plugin install universal-dev-standards@asia-ostrich

Benefits:

• Single command installation
• Automatic updates when new versions are released
• All 15 skills loaded instantly

Migrating from v3.2.x? If you used the old marketplace name:

/plugin uninstall universal-dev-standards@universal-dev-standards
/plugin install universal-dev-standards@asia-ostrich

Method 2: UDS CLI (Recommended for OpenCode)

For OpenCode and other tools, use the UDS CLI:

# Install UDS CLI globally
npm install -g universal-dev-standards

# Initialize project - select your AI tool
uds init

# Skills will be installed to .claude/skills/
# OpenCode auto-detects this path ✅

Use uds check to verify installation status and skills compatibility.

Method 3: Manual Installation

Clone and copy skills directly:

macOS / Linux:

git clone https://github.com/AsiaOstrich/universal-dev-standards.git /tmp/uds
cp -r /tmp/uds/skills/claude-code/* ~/.claude/skills/    # Global
# Or: cp -r /tmp/uds/skills/claude-code/* .claude/skills/  # Project
rm -rf /tmp/uds

Windows (PowerShell):

git clone https://github.com/AsiaOstrich/universal-dev-standards.git $env:TEMP\uds
Copy-Item -Recurse $env:TEMP\uds\skills\claude-code\* $env:USERPROFILE\.claude\skills\
Remove-Item -Recurse $env:TEMP\uds

Community Marketplaces

Discover and install skills from community platforms:

• n-skills - Curated marketplace for Claude Code, OpenCode, Cursor, and more
• claude-plugins.dev - Auto-indexed skill discovery from GitHub
• agentskills.io - Official Agent Skills specification

Multi-AI Tool Support

Platform Support

Note: UDS CLI is Node.js-based and should work on all platforms. Platform testing refers to verified functionality with AI tools on that OS. See AI Agent Roadmap for detailed status.

Core Principles

1. Universal Applicability - Standards work for any programming language, framework, or domain
2. Modular Design - Pick and choose standards relevant to your project
3. Extensible Architecture - Extend with language-specific, framework-specific, or domain-specific rules
4. Evidence-Based - Standards derived from industry best practices and real-world validation
5. Self-Contained - Each standard is independently usable without dependencies

What's Inside

universal-dev-standards/
├── core/                    # Core universal standards (16 files)
├── ai/                      # AI-optimized standards (.ai.yaml)
├── options/                 # Human-readable option guides
├── skills/                  # AI tool skills (Claude Code, etc.)
├── extensions/              # Language/framework/domain-specific
├── templates/               # Document templates
├── integrations/            # Tool configurations
├── cli/                     # CLI tool (uds command)
├── locales/                 # Translations (zh-TW, zh-CN)
└── adoption/                # Adoption guides

See the full directory structure below.

Standard Levels

Level 1: Essential (Minimum Viable Standards)

Every project MUST have:

• anti-hallucination.md - AI collaboration guidelines
• checkin-standards.md - Quality gates before commit
• commit-message-guide.md - Standardized commit format
• spec-driven-development.md - Spec-Driven Development standards

Estimated Setup Time: 30 minutes

Level 2: Recommended (Professional Quality)

Include Level 1 +:

• git-workflow.md - Branching strategy
• code-review-checklist.md - Review guidelines
• versioning.md - Version management
• changelog-standards.md - Changelog writing guide
• testing-standards.md - Testing pyramid (UT/IT/ST/E2E)
• Language-specific style guide (e.g., csharp-style.md)

Estimated Setup Time: 2 hours

Level 3: Comprehensive (Enterprise Grade)

Include Level 2 +:

• documentation-structure.md - Docs organization
• Framework-specific standards (e.g., dotnet.md)
• Domain-specific standards (e.g., fintech.md)
• OpenSpec integration for spec-driven development
• Full template suite

Estimated Setup Time: 1-2 days

AI-Optimized Standards

Dual-Format Architecture

Using AI-Optimized Standards

# Reference in CLAUDE.md or system prompts
standards:
  source: ai/standards/
  options:
    workflow: ai/options/git-workflow/github-flow.ai.yaml
    commit_language: ai/options/commit-message/english.ai.yaml

Available Options

Standards Coverage

Important: For standards with Skills available, use the Skill OR copy the source document - never both.

See Adoption Guide for complete guidance.

Usage Modes Comparison

When using UDS, you can choose between three usage modes:

Quick Decision Guide

• Personal projects with Claude Code? → Skills Only (standardsScope: minimal)
• Team with multiple AI tools? → Skills + Standards (standardsScope: full)
• Enterprise compliance needs? → Standards Only (no Skills dependency)

See Usage Modes Comparison for detailed analysis including feature coverage, token efficiency, and recommendations.

Customization Guide

Where to Write Customizations

Adapting Standards

1. Language Choice: English, Traditional Chinese, Simplified Chinese commit types
2. Tool Configuration: npm run build, dotnet build, mvn package
3. Threshold Adjustment: Test coverage 80%, max method length 50 lines
4. Scope Definition: Define allowed commit scopes for your modules

Excluding Standards

1. During uds init: Select only needed standards interactively
2. Selective Adoption: Copy only specific files
3. AI Tool Exclusions: Add exclusion patterns to CLAUDE.md or .cursorrules
4. Project-Level Overrides: Create PROJECT-STANDARDS.md to document deviations

Multi-Language Support

Commit Message Language Examples

English:

feat(auth): Add OAuth2 support
fix(api): Resolve memory leak

Traditional Chinese:

新增(認證): 實作 OAuth2 支援
修正(API): 解決記憶體洩漏

Simplified Chinese:

新增(认证): 实现 OAuth2 支持
修正(API): 解决内存泄漏

Tool Integration

Git Hooks

npm install --save-dev @commitlint/{cli,config-conventional} husky
npx husky install
npx husky add .husky/commit-msg 'npx commitlint --edit $1'

CI/CD Integration

# .github/workflows/quality-gate.yml
name: Quality Gate
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx commitlint --from HEAD~1 --to HEAD --verbose
      - run: npm run build
      - run: npm test -- --coverage
      - run: npm run lint

OpenSpec Integration

cp -r integrations/openspec/ your-project/openspec/
mkdir -p your-project/.claude/commands/
cp integrations/openspec/commands/* your-project/.claude/commands/

Examples

Example 1: .NET Web API Project

Core Standards: anti-hallucination.md, checkin-standards.md, commit-message-guide.md, git-workflow.md (GitFlow)
Extensions: languages/csharp-style.md, frameworks/dotnet.md
Templates: CLAUDE.md (customized for .NET), README.md, CONTRIBUTING.md

Example 2: React SPA Project

Core Standards: anti-hallucination.md, checkin-standards.md, commit-message-guide.md, git-workflow.md (GitHub Flow)
Extensions: languages/typescript-style.md, frameworks/react.md
Tools: ESLint + Prettier, Husky + commitlint, Jest + React Testing Library

Example 3: Python ML Project

Core Standards: anti-hallucination.md, checkin-standards.md, commit-message-guide.md, git-workflow.md (Trunk-Based)
Extensions: languages/python-style.md, domains/machine-learning.md
Tools: Black, pylint, pytest, mypy

Contributing

How to Contribute

1. Suggest Improvements: Open an issue describing the problem and proposed solution
2. Add Examples: Submit examples of how you've applied these standards
3. Extend Standards: Contribute new language/framework/domain extensions
4. Translate: Help translate standards to other languages

Contribution Guidelines

All contributions must:

• Maintain language/framework/domain agnosticism (for core standards)
• Include examples in at least 2 different contexts
• Follow the existing documentation structure
• Be licensed under CC BY 4.0

Further Reading

Related Standards and Frameworks

• Conventional Commits
• Semantic Versioning
• Keep a Changelog
• Git Best Practices
• Code Review Best Practices

Books and Articles

• The Art of Readable Code by Boswell & Foucher
• Clean Code by Robert C. Martin
• The Pragmatic Programmer by Hunt & Thomas
• Accelerate by Forsgren, Humble, and Kim

Version History

See CHANGELOG.md for complete version history.

License

Both licenses are permissive and allow commercial use, modification, and redistribution. See LICENSE for full details.

Community

• Issues: Report bugs or suggest improvements
• Discussions: Share how you're using these standards
• Examples: Submit your project as an example

Checklist for Adopting Standards

• [ ] Choose installation method (Marketplace / npm / manual)
• [ ] Run uds init or copy core standards
• [ ] Add language/framework extensions if needed
• [ ] Configure project-specific settings in CONTRIBUTING.md
• [ ] Set up Git hooks (commitlint, pre-commit)
• [ ] Integrate quality gates in CI/CD
• [ ] Train team on standards
• [ ] Create first commit following standards

Ready to improve your project's quality? Start with Quick Start above!

Maintained with love by the open-source community

Detailed Directory Structure

universal-dev-standards/
├── core/                                  # Core universal standards (16 files)
│   ├── anti-hallucination.md             # AI collaboration guidelines
│   ├── changelog-standards.md            # Changelog writing guide
│   ├── checkin-standards.md              # Code check-in quality gates
│   ├── code-review-checklist.md          # Code review guidelines
│   ├── commit-message-guide.md           # Commit message conventions
│   ├── documentation-structure.md        # Documentation organization
│   ├── documentation-writing-standards.md # Documentation writing guide
│   ├── error-code-standards.md           # Error code conventions
│   ├── git-workflow.md                   # Git branching strategies
│   ├── logging-standards.md              # Logging standards
│   ├── project-structure.md              # Project directory conventions
│   ├── spec-driven-development.md        # SDD methodology & standards
│   ├── test-completeness-dimensions.md   # Test completeness dimensions
│   ├── test-driven-development.md        # TDD methodology
│   ├── testing-standards.md              # Testing standards (UT/IT/ST/E2E)
│   └── versioning.md                     # Semantic versioning guide
│
├── ai/                             # AI-optimized standards (v2.3.0)
│   ├── standards/                 # Token-efficient YAML format (~80% reduction)
│   │   ├── git-workflow.ai.yaml
│   │   ├── commit-message.ai.yaml
│   │   ├── testing.ai.yaml
│   │   └── ...
│   └── options/                   # Configurable options
│       ├── git-workflow/          # github-flow, gitflow, trunk-based, etc.
│       ├── commit-message/        # english, traditional-chinese, bilingual
│       ├── testing/               # unit, integration, system, e2e
│       └── project-structure/     # nodejs, python, dotnet, java, go
│
├── options/                        # Human-readable option guides (Markdown)
│   ├── git-workflow/              # Detailed workflow documentation
│   ├── commit-message/            # Commit language guides
│   ├── testing/                   # Testing level guides
│   └── project-structure/         # Language-specific project structures
│
├── skills/                         # AI tool skills (v2.1.0)
│   ├── claude-code/               # Claude Code Skills (15 skills)
│   ├── cursor/                    # Cursor Rules (planned)
│   ├── windsurf/                  # Windsurf Rules (planned)
│   ├── cline/                     # Cline Rules (planned)
│   ├── copilot/                   # GitHub Copilot (planned)
│   └── _shared/                   # Shared templates
│
├── extensions/                     # Optional extensions
│   ├── languages/                 # Language-specific standards
│   │   ├── csharp-style.md        # C# coding conventions
│   │   └── php-style.md           # PHP 8.1+ style guide
│   ├── frameworks/                # Framework-specific standards
│   │   └── fat-free-patterns.md   # Fat-Free Framework patterns
│   ├── locales/                   # Locale-specific standards
│   │   └── zh-tw.md               # Traditional Chinese
│   └── domains/                   # Domain-specific standards
│       └── (coming soon)
│
├── templates/                      # Project document templates
│   ├── requirement-*.md           # Requirement templates
│   └── migration-template.md      # Migration plan template
│
├── integrations/                   # Tool configuration files
│   ├── cline/                     # Cline .clinerules
│   ├── cursor/                    # Cursor .cursorrules
│   ├── github-copilot/            # Copilot instructions
│   ├── google-antigravity/        # Antigravity integration
│   ├── windsurf/                  # Windsurf .windsurfrules
│   └── openspec/                  # OpenSpec framework
│
├── cli/                           # CLI tool
│   └── (uds command)
│
├── locales/                       # Translations
│   ├── zh-TW/                     # Traditional Chinese
│   └── zh-CN/                     # Simplified Chinese
│
└── adoption/                       # Adoption guides
    └── ADOPTION-GUIDE.md