universal-dev-standards 4.1.0 → 5.0.0-beta.10

package/bundled/core/ai-agreement-standards.md

@@ -0,0 +1,95 @@
+# AI Agreement Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/ai-agreement-standards.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-29
+**Applicability**: All AI-assisted development sessions
+**Scope**: universal
+**Industry Standards**: ISO 12207 §6.1
+**References**: [iso.org](https://www.iso.org/standard/63712.html)
+**ISO 12207 Mapping**: Agreement Processes (6.1)
+
+---
+
+## Purpose
+
+This standard formalizes the interaction between Human (Acquirer) and AI (Supplier) as a verifiable agreement. In "Vibe Coding," the prompt context serves as the legal contract that governs the AI's behavior and deliverables.
+
+---
+
+## 1. The Context Contract (上下文合約)
+
+Every AI session MUST begin with a clear Context Contract. This is typically implemented via system prompt files (e.g., `CLAUDE.md`, `.cursorrules`).
+
+### 1.1 Contract Components
+
+A valid Context Contract must define:
+
+| Component | Description | Example |
+|-----------|-------------|---------|
+| **Role Definition** | Who represents the User vs. AI | "You are a Senior Backend Engineer..." |
+| **Scope of Work** | Operational boundaries | "Only modify files in `src/utils/`. Do not touch `config/`." |
+| **Constraint Laws** | Non-negotiable rules | "Never hardcode secrets. Always use TypeScript." |
+| **Acceptance Criteria** | Definition of Done | "Code must pass `npm test` and `npm run lint`." |
+
+---
+
+## 2. Request for Proposal (RFP) Standard
+
+Complex tasks should be structured as an "RFP" (Request for Proposal) rather than a simple chat message.
+
+### 2.1 RFP Prompt Structure
+
+When requesting complex features or refactoring, use this structure:
+
+```markdown
+# Objective
+[One-line summary of the task]
+
+# Context & Constraints
+- **Current State**: [Describe existing code/architecture]
+- **Target State**: [Describe desired outcome]
+- **Constraints**: [e.g., "Must use library X", "Max complexity N"]
+
+# Input Data
+[List relevant files or paste JSON schemas]
+
+# Deliverable Requirements
+1. [Requirement A]
+2. [Requirement B]
+
+# Verification Plan
+- [ ] [Test case 1]
+- [ ] [Test case 2]
+```
+
+---
+
+## 3. Supply Acceptance (交付驗收)
+
+### 3.1 AI Self-Verification
+Before outputting code, the AI (Supplier) MUST verify its own output against the Context Contract:
+- Does this code violate any Constraint Laws?
+- Does it meet all Acceptance Criteria?
+
+### 3.2 Human Sign-off
+The User (Acquirer) MUST strictly review the "Supply" (AI output) before applying it:
+- **Review**: Read the code (do not just trust).
+- **Verify**: Run the Verification Plan.
+- **Accept**: Commit the changes only after validation.
+
+---
+
+## Related Standards
+
+- [Anti-Hallucination Protocol](anti-hallucination.md)
+- [Requirement Engineering](requirement-engineering.md)
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-29 | Initial release mapping to ISO 12207 Agreement Processes |

package/bundled/core/ai-friendly-architecture.md

@@ -0,0 +1,544 @@
+# AI-Friendly Architecture Standards
+
+> **Language**: English | [繁體中文](../locales/zh-TW/core/ai-friendly-architecture.md)
+
+**Version**: 1.0.0
+**Last Updated**: 2026-01-21
+**Applicability**: All software projects collaborating with AI assistants
+**Scope**: partial
+**Industry Standards**: None (Emerging AI collaboration practice)
+
+---
+
+## Purpose
+
+This standard defines architecture and documentation practices that maximize the effectiveness of AI-assisted development. By following these guidelines, projects become more analyzable, understandable, and modifiable by AI tools while maintaining human readability.
+
+**Reference Concepts**:
+- RLM (Recursive Language Model) context management principles
+- Token-aware documentation design
+- Modular architecture for AI comprehension
+
+---
+
+## Table of Contents
+
+1. [Core Principles](#core-principles)
+2. [Module Design Standards](#module-design-standards)
+3. [Context Boundary Markers](#context-boundary-markers)
+4. [Documentation Layering](#documentation-layering)
+5. [Metadata Standards](#metadata-standards)
+6. [Query Interface Design](#query-interface-design)
+7. [AI Context Configuration](#ai-context-configuration)
+8. [Anti-Patterns](#anti-patterns)
+9. [Implementation Checklist](#implementation-checklist)
+
+---
+
+## Core Principles
+
+### 1. Explicit Over Implicit
+
+AI assistants perform best when behavior and structure are explicitly documented rather than implied through convention.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                 Explicit vs Implicit                         │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  ❌ IMPLICIT (Hard for AI)                                  │
+│  └── Magic naming conventions                               │
+│  └── Undocumented folder structures                         │
+│  └── Convention-based routing                               │
+│  └── Assumed knowledge of framework behavior                │
+│                                                              │
+│  ✅ EXPLICIT (AI-Friendly)                                  │
+│  └── Documented module responsibilities                     │
+│  └── Clear entry point annotations                          │
+│  └── Explicit dependency declarations                       │
+│  └── Self-documenting configuration files                   │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 2. Layered Context
+
+Structure documentation in layers so AI can access appropriate detail levels based on task complexity.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│               Context Layering Strategy                      │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  Layer 1: Quick Reference (< 500 tokens)                    │
+│  └── One-liner descriptions                                 │
+│  └── API signatures only                                    │
+│  └── Key entry points                                       │
+│                                                              │
+│  Layer 2: Detailed Guide (< 5,000 tokens)                   │
+│  └── Full API documentation                                 │
+│  └── Usage examples                                         │
+│  └── Configuration options                                  │
+│                                                              │
+│  Layer 3: Full Examples (unlimited)                         │
+│  └── Complete implementation examples                       │
+│  └── Edge case documentation                                │
+│  └── Migration guides                                       │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### 3. Semantic Boundaries
+
+Design clear module boundaries that allow AI to analyze components independently without requiring full project context.
+
+### 4. Discoverable Structure
+
+Ensure project structure can be understood by analyzing configuration files and entry points without reading all source code.
+
+---
+
+## Module Design Standards
+
+### Single Responsibility at Module Level
+
+Each module should have a clearly defined, singular purpose that can be summarized in one sentence.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│              Module Header Template                          │
+├─────────────────────────────────────────────────────────────┤
+│                                                              │
+│  /**                                                         │
+│   * @module auth                                             │
+│   * @description Handles user authentication and session    │
+│   *              management for the application.            │
+│   *                                                          │
+│   * @responsibility Authentication and authorization         │
+│   * @dependencies [database, crypto, config]                │
+│   * @exports {login, logout, verify, refreshToken}          │
+│   * @entrypoint ./index.ts                                  │
+│   */                                                         │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Clear Input/Output Contracts
+
+Every public interface should have explicit type definitions or documentation.
+
+| Element | Requirement | Example |
+|---------|-------------|---------|
+| Function Parameters | Type + description | `@param {string} email - User's email address` |
+| Return Values | Type + possible values | `@returns {Promise<User \| null>}` |
+| Side Effects | Documented explicitly | `@sideeffect Writes to database` |
+| Error Conditions | All possible errors | `@throws {AuthError} Invalid credentials` |
+
+### Explicit Dependency Declaration
+
+Dependencies should be declared at module level, not hidden in implementation details.
+
+**JavaScript/TypeScript:**
+```javascript
+// module: src/auth/index.ts
+// dependencies: [database, crypto, config]
+import { db } from '../database';
+import { hash } from '../crypto';
+import { config } from '../config';
+```
+
+**Python:**
+```python
+# module: src/auth/__init__.py
+# dependencies: [database, crypto, config]
+from ..database import db
+from ..crypto import hash_password
+from ..config import settings
+```
+
+---
+
+## Context Boundary Markers
+
+### Module Header Comments
+
+Use standardized header comments that AI can parse for quick module understanding.
+
+```javascript
+/**
+ * ═══════════════════════════════════════════════════════════
+ * MODULE: Payment Processing
+ * ═══════════════════════════════════════════════════════════
+ *
+ * PURPOSE: Handles all payment-related operations including
+ *          processing, refunds, and subscription management.
+ *
+ * DEPENDENCIES:
+ *   - stripe: Payment gateway integration
+ *   - database: Transaction storage
+ *   - events: Payment event publishing
+ *
+ * EXPORTS:
+ *   - processPayment(amount, method): Process single payment
+ *   - refund(transactionId): Issue refund
+ *   - createSubscription(plan): Start subscription
+ *
+ * CONFIGURATION:
+ *   - STRIPE_SECRET_KEY: Required
+ *   - PAYMENT_WEBHOOK_SECRET: Required
+ *
+ * ═══════════════════════════════════════════════════════════
+ */
+```
+
+### Section Dividers
+
+Use consistent section dividers within large files:
+
+```javascript
+// ============================================================
+// SECTION: Validation Helpers
+// ============================================================
+
+// ... validation code ...
+
+// ============================================================
+// SECTION: API Handlers
+// ============================================================
+
+// ... handler code ...
+```
+
+---
+
+## Documentation Layering
+
+### Level 1: Quick Reference (< 500 tokens)
+
+Create `QUICK-REF.md` in each major module:
+
+```markdown
+# Auth Module - Quick Reference
+
+## Purpose
+User authentication and session management.
+
+## Key Functions
+- `login(email, password)` → `Promise<Session>`
+- `logout(sessionId)` → `void`
+- `verify(token)` → `Promise<User | null>`
+
+## Configuration
+- `AUTH_SECRET`: JWT signing secret
+- `SESSION_DURATION`: Session lifetime (default: 24h)
+
+## Entry Point
+`src/auth/index.ts`
+```
+
+### Level 2: Detailed Guide (< 5,000 tokens)
+
+Main `README.md` with comprehensive documentation:
+
+```markdown
+# Authentication Module
+
+## Overview
+[2-3 paragraph description]
+
+## Architecture
+[Diagram or description of internal structure]
+
+## API Reference
+[Full function signatures with parameters]
+
+## Configuration Options
+[All configuration with defaults and descriptions]
+
+## Usage Examples
+[Common use cases with code samples]
+
+## Error Handling
+[Error types and handling strategies]
+```
+
+### Level 3: Full Examples (unlimited)
+
+Separate `examples/` directory with complete implementations:
+
+```
+auth/
+├── QUICK-REF.md          # Level 1
+├── README.md             # Level 2
+└── examples/             # Level 3
+    ├── basic-login.ts
+    ├── oauth-integration.ts
+    └── custom-middleware.ts
+```
+
+---
+
+## Metadata Standards
+
+### Package Metadata Extensions
+
+Extend standard package files with AI-relevant metadata:
+
+**package.json (JavaScript/TypeScript):**
+```json
+{
+  "name": "my-project",
+  "ai-context": {
+    "entryPoints": ["src/index.ts", "src/api/index.ts"],
+    "modules": {
+      "auth": "src/auth/",
+      "api": "src/api/",
+      "database": "src/db/"
+    },
+    "ignorePatterns": ["node_modules", "dist", "coverage"],
+    "quickRef": "docs/QUICK-REF.md"
+  }
+}
+```
+
+**pyproject.toml (Python):**
+```toml
+[tool.ai-context]
+entry_points = ["src/main.py", "src/api/__init__.py"]
+modules = { auth = "src/auth/", api = "src/api/" }
+ignore_patterns = ["__pycache__", ".venv", "*.pyc"]
+quick_ref = "docs/QUICK-REF.md"
+```
+
+### .ai-context.yaml Configuration
+
+Dedicated AI context configuration file:
+
+```yaml
+# .ai-context.yaml - AI Context Configuration
+version: 1.0.0
+
+project:
+  name: my-project
+  type: web-app  # web-app | library | cli | api | monorepo
+  primary-language: typescript
+
+modules:
+  - name: auth
+    path: src/auth/
+    entry: index.ts
+    description: Authentication and authorization
+    dependencies: [database, crypto]
+    priority: high
+
+  - name: api
+    path: src/api/
+    entry: routes.ts
+    description: REST API endpoints
+    dependencies: [auth, database]
+    priority: high
+
+  - name: utils
+    path: src/utils/
+    entry: index.ts
+    description: Shared utility functions
+    dependencies: []
+    priority: low
+
+analysis-hints:
+  entry-points:
+    - src/main.ts
+    - src/index.ts
+  ignore-patterns:
+    - node_modules
+    - dist
+    - coverage
+    - "*.test.ts"
+  architecture-type: layered  # layered | microservices | modular | monolith
+
+documentation:
+  quick-ref: docs/QUICK-REF.md
+  detailed: docs/ARCHITECTURE.md
+  examples: docs/examples/
+
+context-strategy:
+  max-chunk-size: 50000
+  overlap: 500
+  analysis-pattern: hierarchical
+```
+
+---
+
+## Query Interface Design
+
+### Structured API Documentation Format
+
+Design API documentation that's easy to query:
+
+```markdown
+## API: createUser
+
+**Endpoint**: `POST /api/users`
+**Module**: `src/api/users.ts:45`
+
+### Parameters
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| email | string | Yes | User's email address |
+| password | string | Yes | Min 8 characters |
+| name | string | No | Display name |
+
+### Response
+```json
+{
+  "id": "string",
+  "email": "string",
+  "createdAt": "ISO8601"
+}
+```
+
+### Errors
+| Code | Condition |
+|------|-----------|
+| 400 | Invalid email format |
+| 409 | Email already exists |
+
+### Example
+```javascript
+const user = await api.createUser({
+  email: 'user@example.com',
+  password: 'securePassword123'
+});
+```
+```
+
+### Searchable Code Annotations
+
+Use consistent annotation patterns that AI can search for:
+
+```javascript
+// @ai-hint: This function is performance-critical
+// @ai-complexity: O(n log n)
+// @ai-dependencies: [sortUtils, comparators]
+function sortLargeDataset(data) {
+  // ...
+}
+
+// @ai-security: Validates user input
+// @ai-validation: email, password strength
+function validateRegistration(input) {
+  // ...
+}
+```
+
+---
+
+## AI Context Configuration
+
+### Recommended Directory Structure
+
+```
+project/
+├── .ai-context.yaml          # AI context configuration
+├── docs/
+│   ├── QUICK-REF.md          # Level 1 documentation
+│   ├── ARCHITECTURE.md       # Level 2 documentation
+│   └── examples/             # Level 3 documentation
+├── src/
+│   ├── auth/
+│   │   ├── index.ts          # Entry point with module header
+│   │   ├── QUICK-REF.md      # Module-level quick reference
+│   │   └── README.md         # Module documentation
+│   ├── api/
+│   │   ├── index.ts
+│   │   └── README.md
+│   └── index.ts              # Application entry point
+└── CLAUDE.md / INSTRUCTIONS.md  # AI instruction file
+```
+
+### Context Priority Guidelines
+
+When AI context is limited, prioritize:
+
+| Priority | Content Type | Reason |
+|----------|--------------|--------|
+| 1 | Entry points | Understand application structure |
+| 2 | .ai-context.yaml | Module map and dependencies |
+| 3 | QUICK-REF files | Rapid API understanding |
+| 4 | Modified files | Direct task relevance |
+| 5 | Dependency chain | Context for changes |
+
+---
+
+## Anti-Patterns
+
+### ❌ Patterns to Avoid
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Magic strings** | AI can't trace constants | Use typed constants with documentation |
+| **Implicit routing** | Hidden behavior | Document route mappings explicitly |
+| **Global state** | Unpredictable dependencies | Dependency injection with explicit wiring |
+| **Circular dependencies** | Context confusion | Clear hierarchical dependencies |
+| **Monolithic files** | Context overflow | Split into focused modules |
+| **Convention over documentation** | Assumed knowledge | Explicit documentation |
+
+### ❌ Documentation Anti-Patterns
+
+| Anti-Pattern | Problem | Solution |
+|--------------|---------|----------|
+| **Outdated docs** | Misleading AI | Keep docs in sync with code |
+| **Generated only** | Missing context | Add human-written context |
+| **No examples** | Ambiguous usage | Include working examples |
+| **Wall of text** | Hard to parse | Use structured formats |
+
+---
+
+## Implementation Checklist
+
+### Quick Start (< 1 hour)
+
+- [ ] Create `.ai-context.yaml` with module list
+- [ ] Add `QUICK-REF.md` to project root
+- [ ] Document entry points in README
+- [ ] Add module headers to main files
+
+### Standard Implementation (< 1 day)
+
+- [ ] Complete `.ai-context.yaml` configuration
+- [ ] Add `QUICK-REF.md` to each major module
+- [ ] Document all public APIs with type information
+- [ ] Add section dividers to large files
+- [ ] Create dependency documentation
+
+### Full Implementation (< 1 week)
+
+- [ ] Three-layer documentation for all modules
+- [ ] Searchable code annotations
+- [ ] Examples directory with use cases
+- [ ] Architecture diagrams
+- [ ] Integration with CI for doc validation
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0.0 | 2026-01-21 | Initial release |
+
+---
+
+## Related Standards
+
+- [Project Structure](./project-structure.md) - Directory organization
+- [Documentation Structure](./documentation-structure.md) - Documentation organization
+- [Anti-Hallucination](./anti-hallucination.md) - AI accuracy standards
+
+---
+
+## License
+
+This standard is released under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
+
+**Source**: [universal-dev-standards](https://github.com/AsiaOstrich/universal-dev-standards)

package/bundled/core/ai-instruction-standards.md

@@ -5,6 +5,8 @@
 **Version**: 1.0.0
 **Last Updated**: 2026-01-14
 **Applicability**: All projects using AI coding assistants
+**Scope**: partial
+**Industry Standards**: None (Emerging AI tool practice)
 
 ---