Language: English | 繁體中文
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)
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
- Core Principles
- Module Design Standards
- Context Boundary Markers
- Documentation Layering
- Metadata Standards
- Query Interface Design
- AI Context Configuration
- Anti-Patterns
- Implementation Checklist
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 │
│ │
└─────────────────────────────────────────────────────────────┘
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 │
│ │
└─────────────────────────────────────────────────────────────┘
Design clear module boundaries that allow AI to analyze components independently without requiring full project context.
Ensure project structure can be understood by analyzing configuration files and entry points without reading all source code.
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 │
│ */ │
│ │
└─────────────────────────────────────────────────────────────┘
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 |
Dependencies should be declared at module level, not hidden in implementation details.
JavaScript/TypeScript:
// module: src/auth/index.ts
// dependencies: [database, crypto, config]
import { db } from '../database';
import { hash } from '../crypto';
import { config } from '../config';Python:
# module: src/auth/__init__.py
# dependencies: [database, crypto, config]
from ..database import db
from ..crypto import hash_password
from ..config import settingsUse standardized header comments that AI can parse for quick module understanding.
/**
* ═══════════════════════════════════════════════════════════
* 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
*
* ═══════════════════════════════════════════════════════════
*/Use consistent section dividers within large files:
// ============================================================
// SECTION: Validation Helpers
// ============================================================
// ... validation code ...
// ============================================================
// SECTION: API Handlers
// ============================================================
// ... handler code ...Create QUICK-REF.md in each major module:
# 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`Main README.md with comprehensive documentation:
# 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]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
Extend standard package files with AI-relevant metadata:
package.json (JavaScript/TypeScript):
{
"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):
[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"Dedicated AI context configuration file:
# .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: hierarchicalDesign API documentation that's easy to query:
## 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"
}| Code | Condition |
|---|---|
| 400 | Invalid email format |
| 409 | Email already exists |
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) {
// ...
}
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
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-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 |
| 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 |
- Create
.ai-context.yamlwith module list - Add
QUICK-REF.mdto project root - Document entry points in README
- Add module headers to main files
- Complete
.ai-context.yamlconfiguration - Add
QUICK-REF.mdto each major module - Document all public APIs with type information
- Add section dividers to large files
- Create dependency documentation
- Three-layer documentation for all modules
- Searchable code annotations
- Examples directory with use cases
- Architecture diagrams
- Integration with CI for doc validation
| Version | Date | Changes |
|---|---|---|
| 1.0.0 | 2026-01-21 | Initial release |
- Project Structure - Directory organization
- Documentation Structure - Documentation organization
- Anti-Hallucination - AI accuracy standards
This standard is released under CC BY 4.0.
Source: universal-dev-standards