Universal Development Standards

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

Version: 4.1.0 | Released: 2026-01-21 | License: Dual License (CC BY 4.0 + MIT)

Language-agnostic, framework-agnostic documentation standards for software projects. Ensure consistency, quality, and maintainability across diverse technology stacks.

Features

Category	Count	Description
Core Standards	22	Universal development guidelines (Markdown)
AI Skills	23	Interactive Claude Code skills for AI-assisted development
Slash Commands	24	Quick actions (`/commit`, `/tdd`, `/review`, etc.)
CLI Commands	6	`list`, `init`, `configure`, `check`, `update`, `skills`
Languages	3	English, Traditional Chinese, Simplified Chinese

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

For manual setup without npm, see Installation Methods below.

Note: Copying standards alone won't enable AI assistance. Use uds init to automatically configure your AI tool or manually reference standards in your tool's configuration file.

Installation Methods

CLI Tool (Primary)

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

Specific Version

npm install -g universal-dev-standards@4.1.0
npm install -g universal-dev-standards@beta  # Preview features

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

AI Tool Support

AI Tool	Status	Skills	Commands	Configuration
Claude Code	✅ Complete	✅	Built-in	`CLAUDE.md`
OpenCode	✅ Complete	✅	✅	`AGENTS.md`
Cline	🔶 Partial	✅	-	`.clinerules`
GitHub Copilot	🔶 Partial	✅	✅	`copilot-instructions.md`
OpenAI Codex	🔶 Partial	✅	-	`AGENTS.md`
Gemini CLI	🧪 Preview	✅	✅	`GEMINI.md`
Roo Code	⏳ Planned	✅	✅	`.roorules`
Cursor	📄 Minimal	-	-	`.cursorrules`
Windsurf	📄 Minimal	-	-	`.windsurfrules`
Antigravity	📄 Minimal	-	-	`INSTRUCTIONS.md`

Status Legend (UDS CLI implementation status):

✅ Complete = Full Skills + Commands support, tested

🔶 Partial = Skills work, Commands limited or unsupported

🧪 Preview = Functional but preview-level support

⏳ Planned = Code exists, testing pending

📄 Minimal = Rules file only, no Skills/Commands

Platform Support

Platform	Status	Notes
macOS	✅ Tested	Primary development platform
Linux	⚠️ Untested	Expected to work (Node.js based)
Windows	⚠️ Untested	PowerShell scripts provided

See Windows Guide for platform-specific instructions.

Skills Installation

Method 1: Claude Code Plugin Marketplace (Easiest)

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

Benefits: Single command, automatic updates, all 23 skills loaded instantly.

Migrating from v3.x?

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

Method 2: UDS CLI

npm install -g universal-dev-standards
uds init  # Select your AI tool, skills auto-installed

Use uds check to verify installation status.

Method 3: Manual Installation

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

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

Usage Modes

Mode	Best For	Key Advantage
Skills Only	Individual developers + Claude Code	Lowest token usage, best interactive experience
Standards Only	Multi-tool teams / Enterprise	Full customization, version control
Skills + Standards	Complete experience / Learning	100% feature coverage

Quick Decision Guide

Personal projects with Claude Code? → Skills Only
Team with multiple AI tools? → Skills + Standards
Enterprise compliance needs? → Standards Only

See Usage Modes Comparison for detailed analysis.

Core Standards Overview

Level 1: Essential (30 minutes setup)

Every project MUST have:

Standard	Description
`anti-hallucination.md`	AI collaboration guidelines
`checkin-standards.md`	Quality gates before commit
`commit-message-guide.md`	Conventional Commits format
`spec-driven-development.md`	Specification-first approach

Level 2: Recommended (2 hours setup)

Include Level 1 plus:

Standard	Description
`git-workflow.md`	Branching strategies (GitHub Flow, GitFlow, Trunk-Based)
`code-review-checklist.md`	Systematic review guidelines
`versioning.md`	Semantic Versioning (SemVer)
`changelog-standards.md`	Keep a Changelog format
`testing-standards.md`	Testing pyramid (70/20/7/3)
`test-driven-development.md`	TDD methodology
`behavior-driven-development.md`	BDD with Given-When-Then

Level 3: Comprehensive (1-2 days setup)

Include Level 2 plus:

Standard	Description
`documentation-structure.md`	Documentation organization
`project-structure.md`	Directory conventions
`acceptance-test-driven-development.md`	ATDD methodology
`refactoring-standards.md`	Safe refactoring practices

See Adoption Guide for complete guidance.

Customization

Where to Write Customizations

Type	File	Location
AI tool rules	`CLAUDE.md`, `.cursorrules`, etc.	Project root
Project overrides	`PROJECT-STANDARDS.md`	Project root
Copied standards	`docs/standards/`	Your project

Adapting Standards

Language: English, Traditional Chinese, or Simplified Chinese commit types
Tools: Configure build commands (npm, dotnet, mvn, etc.)
Thresholds: Adjust test coverage, method length limits
Scopes: Define allowed commit scopes for your modules

Excluding Standards

During uds init: Select only needed standards interactively
Selective Adoption: Copy only specific files
AI Tool Exclusions: Add patterns to CLAUDE.md or .cursorrules

Contributing

How to Contribute

Suggest Improvements: Open an issue with problem and solution
Add Examples: Submit real-world usage examples
Extend Standards: Contribute language/framework/domain extensions
Translate: Help translate to other languages

Guidelines

Maintain language/framework agnosticism for core standards
Include examples in at least 2 different contexts
Follow existing documentation structure
License under CC BY 4.0

See CONTRIBUTING.md for detailed guidelines.

FAQ

How do I choose between Skills Only and Standards Only?

Skills Only: Best for individual developers using Claude Code who want interactive AI assistance with minimal setup
Standards Only: Best for teams using multiple AI tools or requiring enterprise compliance with full version control

Can I adopt only some standards?

Yes! Run uds init and select only the standards you need. You can also manually copy specific files from core/.

How do I update installed skills?

For Plugin Marketplace: Skills update automatically or use /plugin update. For CLI installation: Run uds update --skills.

Does UDS work on Windows?

Yes. The CLI is Node.js-based and works on all platforms. See Windows Guide for PowerShell-specific instructions.

What's the difference between core standards and skills?

Core Standards: Documentation (Markdown) that defines best practices - reference material
Skills: Interactive AI commands that implement those standards - active assistance

Why are some AI tools marked as "Planned"?

We provide configuration files for these tools, but full integration testing is pending. The configurations should work, but edge cases may exist.

Version History

Version	Date	Highlights
4.1.0	2026-01-21	Enhanced refactoring standards
4.0.0	2026-01-20	Bidirectional Derivation; 6 new core standards
3.5.0	2026-01-15	Multi-Agent Skills; Gemini CLI; i18n
3.2.2	2026-01-06	`uds skills` command
3.0.0	2025-12-30	Windows support; npm publish

See CHANGELOG.md for complete history.

What's New in 4.x

4.1.0 Highlights

Enhanced refactoring standards with tactical, strategic, and legacy code safety strategies
Decision matrix for choosing refactoring approach

4.0.0 Highlights

Feature	Description
Bidirectional Derivation	Forward Derivation + Reverse Engineering for complete spec-code lifecycle
6 New Core Standards	BDD, ATDD, Reverse Engineering, Forward Derivation, AI Instructions, Refactoring
23 Skills	7 new skills including Forward Derivation, BDD/ATDD assistants
24 Slash Commands	9 new commands (`/derive-`, `/reverse-`, `/atdd`, `/bdd`)
Methodology System	TDD/BDD/SDD/ATDD workflows now production-ready

License

Component	License	Allows
Documentation	CC BY 4.0	Commercial use, modification, redistribution with attribution
CLI Tool	MIT	Commercial use, modification, redistribution

See LICENSE for full details.

Directory Structure

universal-dev-standards/
├── core/                    # Core standards (22 files)
│   ├── anti-hallucination.md
│   ├── commit-message-guide.md
│   ├── testing-standards.md
│   └── ...
├── ai/                      # AI-optimized formats (.ai.yaml)
├── skills/                  # AI tool skills
│   └── claude-code/         # 23 skill directories
├── extensions/              # Language/framework extensions
│   ├── languages/           # csharp-style.md, php-style.md
│   └── frameworks/          # fat-free-patterns.md
├── integrations/            # AI tool configurations
│   ├── cursor/              # .cursorrules
│   ├── windsurf/            # .windsurfrules
│   └── ...
├── cli/                     # CLI tool (uds command)
├── locales/                 # Translations
│   ├── zh-TW/               # Traditional Chinese
│   └── zh-CN/               # Simplified Chinese
├── templates/               # Document templates
└── adoption/                # Adoption guides

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

Maintained with ❤️ by the open-source community

Name		Name	Last commit message	Last commit date
Latest commit History 330 Commits
.claude-plugin		.claude-plugin
.github		.github
.standards		.standards
adoption		adoption
ai		ai
cli		cli
core		core
docs		docs
extensions		extensions
integrations		integrations
locales		locales
methodologies		methodologies
options		options
scripts		scripts
skills		skills
specs		specs
templates		templates
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MAINTENANCE.md		MAINTENANCE.md
README.md		README.md
STANDARDS-MAPPING.md		STANDARDS-MAPPING.md
package-lock.json		package-lock.json
package.json		package.json

License

AsiaOstrich/universal-dev-standards

Folders and files

Latest commit

History

Repository files navigation

Universal Development Standards

Features

Quick Start

Install via npm (Recommended)

Or use npx (No installation required)

Manual Setup

Installation Methods

CLI Tool (Primary)

AI Tool Support

Platform Support

Skills Installation

Method 1: Claude Code Plugin Marketplace (Easiest)

Method 2: UDS CLI

Method 3: Manual Installation

Community Marketplaces

Usage Modes

Quick Decision Guide

Core Standards Overview

Level 1: Essential (30 minutes setup)

Level 2: Recommended (2 hours setup)

Level 3: Comprehensive (1-2 days setup)

Customization

Where to Write Customizations

Adapting Standards

Excluding Standards

Contributing

How to Contribute

Guidelines

FAQ

How do I choose between Skills Only and Standards Only?

Can I adopt only some standards?

How do I update installed skills?

Does UDS work on Windows?

What's the difference between core standards and skills?

Why are some AI tools marked as "Planned"?

Further Reading

Related Standards

Recommended Books

Version History

What's New in 4.x

4.1.0 Highlights

4.0.0 Highlights

License

Directory Structure

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases 73

Packages 0

Contributors 2

Languages

Packages