Universal Development Standards

Language: English | 繁體中文

Version: 2.2.0 Last Updated: 2025-12-25 License: Dual License (CC BY 4.0 + MIT)

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

🎯 Core Principles

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

📦 What's Inside

universal-dev-standards/
├── core/                           # Core universal standards
│   ├── anti-hallucination.md      # AI collaboration guidelines
│   ├── checkin-standards.md       # Code check-in quality gates
│   ├── commit-message-guide.md    # Commit message conventions
│   ├── spec-driven-development.md # SDD methodology & standards
│   ├── git-workflow.md            # Git branching strategies
│   ├── code-review-checklist.md   # Code review guidelines
│   ├── documentation-structure.md # Documentation organization
│   ├── project-structure.md       # Project directory conventions
│   ├── versioning.md              # Semantic versioning guide
│   ├── changelog-standards.md     # Changelog writing guide
│   └── testing-standards.md       # Testing standards (UT/IT/ST/E2E)
│
├── skills/                         # ✅ NEW: AI tool skills (v2.1.0)
│   ├── claude-code/               # Claude Code 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)
│
└── adoption/                       # Adoption guides
    └── ADOPTION-GUIDE.md

🔗 Standards Adoption

Using with Claude Code (Recommended)

Skills are now included in this repository. Install Claude Code Skills for interactive AI assistance:

# Clone and install skills
git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards/skills/claude-code
./install.sh

Multi-AI Tool Support (Coming Soon)

We're expanding support for more AI coding assistants:

AI Tool	Status	Path
Claude Code	✅ Complete	`skills/claude-code/`
Cursor	🚧 Planned	`skills/cursor/`
Windsurf	🚧 Planned	`skills/windsurf/`
Cline	🚧 Planned	`skills/cline/`
GitHub Copilot	🚧 Planned	`skills/copilot/`

Standards Coverage

Standard	Skill Available	Adoption
anti-hallucination.md	✅ ai-collaboration-standards	Install Skill
commit-message-guide.md	✅ commit-standards	Install Skill
code-review-checklist.md	✅ code-review-assistant	Install Skill
git-workflow.md	✅ git-workflow-guide	Install Skill
versioning.md + changelog-standards.md	✅ release-standards	Install Skill
testing-standards.md	✅ testing-guide	Install Skill
documentation-structure.md	✅ documentation-guide	Install Skill
requirement templates	✅ requirement-assistant	Install Skill
checkin-standards.md	❌	Copy to project
spec-driven-development.md	❌	Copy to project
documentation-writing-standards.md	❌	Copy to project
project-structure.md	❌	Copy to project
Language/Framework extensions	❌	Copy if applicable
AI tool integrations	❌	Copy to tool location

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

📖 See Adoption Guide for complete guidance and checklists.

Using CLI Tool

# Clone and setup CLI (one-time)
git clone https://github.com/AsiaOstrich/universal-dev-standards.git
cd universal-dev-standards/cli && npm install && npm link

# In your project directory
cd your-project
uds init    # Interactive initialization
uds check   # Check adoption status
uds update  # Update to latest version

📖 See CLI README for detailed CLI usage.

🚀 Quick Start

Step 1: Choose Core Standards

Minimal Setup (Required):

# 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/

Recommended Setup:

# Copy all core standards
cp core/*.md your-project/.standards/

Step 2: Add Language/Framework Extensions

For .NET Projects:

cp extensions/languages/csharp-style.md your-project/.standards/
cp extensions/frameworks/dotnet.md your-project/.standards/

For TypeScript Projects:

cp extensions/languages/typescript-style.md your-project/.standards/

For Python Projects:

cp extensions/languages/python-style.md your-project/.standards/

Step 3: Configure Project-Specific Settings

Edit your-project/CONTRIBUTING.md or your-project/.standards/PROJECT-CONFIG.md:

## Documentation Standards Configuration

### Commit Message Language
- Type Language: **English** (feat, fix, refactor)
- Subject Language: **English**

### Git Workflow
- Strategy: **GitFlow**
- Main branches: `main`, `develop`
- Feature branch prefix: `feature/`
- Hotfix branch prefix: `hotfix/`

### Code Quality Tools
- Linter: ESLint
- Formatter: Prettier
- Test Framework: Jest
- Minimum Test Coverage: 80%

### Check-in Requirements
- ✅ Build must pass
- ✅ All tests must pass
- ✅ Linter must pass with 0 errors
- ✅ Test coverage ≥80%

Step 4 (Optional): Use Templates

# Initialize project documentation
cp templates/README.md.template your-project/README.md
cp templates/CONTRIBUTING.md.template your-project/CONTRIBUTING.md
cp templates/CHANGELOG.md.template your-project/CHANGELOG.md

# Customize templates by replacing placeholders
# [PROJECT_NAME] → Your Project Name
# [DESCRIPTION] → Your project description
# etc.

📊 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 Recommended For: All projects, especially AI-assisted development

🟡 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 Recommended For: Team projects, open-source projects

🔵 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 (README, CONTRIBUTING, CHANGELOG, API docs)

Estimated Setup Time: 1-2 days Recommended For: Enterprise projects, regulated industries, large teams

🔧 Customization Guide

Adapting Standards to Your Project

All core standards include "Project-Specific Customization" sections. Customize by:

Language Choice

## Commit Message Language Choice
- English: feat, fix, refactor
- Traditional Chinese: 新增, 修正, 重構
- Spanish: característica, corrección, refactorización

Tool Configuration

## Build Command
```bash
npm run build  # Node.js project
dotnet build   # .NET project
mvn package    # Java project

Threshold Adjustment

## Quality Thresholds
- Test Coverage: 80% (adjust based on project maturity)
- Max Method Length: 50 lines (adjust based on language)
- Max Cyclomatic Complexity: 10 (standard)

Scope Definition

## Allowed Commit Scopes
- auth: Authentication module
- payment: Payment processing
- [add your modules here]

🌍 Multi-Language Support

Commit Message Language Examples

English:

feat(auth): Add OAuth2 support
fix(api): Resolve memory leak
docs(readme): Update installation guide

Traditional Chinese:

新增(認證): 實作 OAuth2 支援
修正(API): 解決記憶體洩漏
文件(README): 更新安裝指南

Spanish:

característica(auth): Agregar soporte OAuth2
corrección(api): Resolver fuga de memoria
documentación(readme): Actualizar guía de instalación

Japanese:

機能(認証): OAuth2サポートを追加
修正(API): メモリリークを解決
文書(README): インストールガイドを更新

🛠️ Tool Integration

Git Hooks

Install commitlint (Node.js projects):

npm install --save-dev @commitlint/{cli,config-conventional}
npm install --save-dev husky

# Initialize husky
npx husky install
npx husky add .husky/commit-msg 'npx commitlint --edit $1'

Configure commitlint:

// .commitlintrc.js
module.exports = {
  extends: ['@commitlint/config-conventional'],
  rules: {
    'type-enum': [
      2,
      'always',
      ['feat', 'fix', 'refactor', 'docs', 'test', 'perf', 'build', 'ci', 'chore']
    ]
  }
};

CI/CD Integration

GitHub Actions Example:

# .github/workflows/quality-gate.yml
name: Quality Gate

on: [push, pull_request]

jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate Commit Messages
        run: npx commitlint --from HEAD~1 --to HEAD --verbose

      - name: Build
        run: npm run build

      - name: Test
        run: npm test -- --coverage

      - name: Lint
        run: npm run lint

      - name: Check Coverage
        run: |
          coverage=$(npx nyc report --reporter=text-summary | grep 'Lines' | awk '{print $3}' | sed 's/%//')
          if (( $(echo "$coverage < 80" | bc -l) )); then
            echo "Coverage $coverage% is below 80%"
            exit 1
          fi

OpenSpec Integration

For spec-driven development, integrate OpenSpec:

# Copy OpenSpec framework
cp -r integrations/openspec/ your-project/openspec/

# Create .claude/commands directory
mkdir -p your-project/.claude/commands/
cp integrations/openspec/commands/* your-project/.claude/commands/

Usage:

# Propose a new change
/openspec proposal "Add user authentication"

# Apply approved spec
/openspec apply specs/auth-feature

# Archive completed spec
/openspec archive specs/auth-feature

📚 Examples

Example 1: .NET Web API Project

Standards Configuration:

✅ Core Standards
   - anti-hallucination.md
   - checkin-standards.md
   - commit-message-guide.md (English types)
   - git-workflow.md (GitFlow)

✅ Extensions
   - languages/csharp-style.md
   - frameworks/dotnet.md

✅ Templates
   - CLAUDE.md (customized for .NET)
   - README.md
   - CONTRIBUTING.md

See examples/dotnet-web-api/ for full implementation.

Example 2: React SPA Project

Standards Configuration:

✅ Core Standards
   - anti-hallucination.md
   - checkin-standards.md
   - commit-message-guide.md (English types)
   - git-workflow.md (GitHub Flow)

✅ Extensions
   - languages/typescript-style.md
   - frameworks/react.md

✅ Tools
   - ESLint + Prettier
   - Husky + commitlint
   - Jest + React Testing Library

See examples/react-spa/ for full implementation.

Example 3: Python ML Project

Standards Configuration:

✅ Core Standards
   - anti-hallucination.md
   - checkin-standards.md
   - commit-message-guide.md (English types)
   - git-workflow.md (Trunk-Based)

✅ Extensions
   - languages/python-style.md
   - domains/machine-learning.md

✅ Tools
   - Black (formatter)
   - pylint (linter)
   - pytest (testing)
   - mypy (type checking)

See examples/python-ml/ for full implementation.

🤝 Contributing

We welcome contributions to improve these standards!

How to Contribute

Suggest Improvements: Open an issue describing the problem and proposed solution
Add Examples: Submit examples of how you've applied these standards
Extend Standards: Contribute new language/framework/domain extensions
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

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

Version	Date	Changes
1.3.0	2025-12-15	Added: changelog-standards.md; Updated: versioning.md, git-workflow.md (cross-references), zh-tw.md (terminology)
1.2.0	2025-12-11	Added: project-structure.md; Updated: documentation-structure.md (file naming, version alignment), checkin-standards.md (directory hygiene)
1.1.0	2025-12-05	Added: testing-standards.md (UT/IT/ST/E2E)
1.0.0	2025-11-12	Initial release with core standards

📄 License

This project uses dual licensing:

Component	License
Documentation (`core/`, `extensions/`, `templates/`, etc.)	CC BY 4.0
CLI Tool (`cli/`)	MIT

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

Copied core standards to project
Chose language/framework extensions
Configured project-specific settings in CONTRIBUTING.md
Set up Git hooks (commitlint, pre-commit)
Integrated quality gates in CI/CD
Trained team on standards
Updated project README to reference standards
Created first commit following standards

Ready to improve your project's documentation quality?

Start with Level 1 (Essential Standards) today!

Maintained with ❤️ by the open-source community

Name		Name	Last commit message	Last commit date
Latest commit History 50 Commits
.github/workflows		.github/workflows
adoption		adoption
cli		cli
core		core
extensions		extensions
integrations		integrations
locales		locales
scripts		scripts
skills		skills
templates		templates
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md

License

AsiaOstrich/universal-dev-standards

Folders and files

Latest commit

History

Repository files navigation

Universal Development Standards

📋 Purpose

🎯 Core Principles

📦 What's Inside

🔗 Standards Adoption

Using with Claude Code (Recommended)

Multi-AI Tool Support (Coming Soon)

Standards Coverage

Using CLI Tool

🚀 Quick Start

Step 1: Choose Core Standards

Step 2: Add Language/Framework Extensions

Step 3: Configure Project-Specific Settings

Step 4 (Optional): Use Templates

📊 Standard Levels

🟢 Level 1: Essential (Minimum Viable Standards)

🟡 Level 2: Recommended (Professional Quality)

🔵 Level 3: Comprehensive (Enterprise Grade)

🔧 Customization Guide

Adapting Standards to Your Project

🌍 Multi-Language Support

Commit Message Language Examples

🛠️ Tool Integration

Git Hooks

CI/CD Integration

OpenSpec Integration

📚 Examples

Example 1: .NET Web API Project

Example 2: React SPA Project

Example 3: Python ML Project

🤝 Contributing

How to Contribute

Contribution Guidelines

📖 Further Reading

Related Standards and Frameworks

Books and Articles

🔄 Version History

📄 License

💬 Community

✅ Checklist for Adopting Standards

About

Topics

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Uh oh!

Languages

Packages