ai-friendly-architecture

name	ai-friendly-architecture
scope	uds-specific
description	Design AI-friendly architecture with explicit patterns, layered documentation, and semantic boundaries. Use when: structuring projects for AI collaboration, optimizing codebase for AI analysis, setting up AI context. Keywords: architecture, AI-friendly, context, modules, documentation layers, .ai-context.yaml, 架構, AI 友善, 上下文.

AI-Friendly Architecture Guide

Language: English | 繁體中文

Version: 1.0.0 Last Updated: 2026-01-25 Applicability: Claude Code Skills

---

Core Standard: This skill implements AI-Friendly Architecture. For comprehensive methodology documentation, refer to the core standard.

Purpose

This skill helps design project architecture that maximizes AI collaboration effectiveness through explicit patterns, layered documentation, and semantic boundaries.

Quick Reference

Core Principles

Principle	Description	Benefit
Explicit Over Implicit	Document behavior explicitly	AI understands without guessing
Layered Context	Multi-level documentation	Appropriate detail per task
Semantic Boundaries	Clear module boundaries	Independent analysis
Discoverable Structure	Self-documenting structure	Quick orientation

Context Layers

Layer	Token Budget	Content
L1: Quick Ref	< 500	One-liners, API signatures, entry points
L2: Detailed	< 5,000	Full API docs, usage examples
L3: Examples	Unlimited	Complete implementations, edge cases

Recommended Structure

project/
├── .ai-context.yaml          # AI context configuration
├── docs/
│   ├── QUICK-REF.md          # Level 1 documentation
│   └── ARCHITECTURE.md       # Level 2 documentation
├── src/
│   └── auth/
│       ├── index.ts          # Entry point with module header
│       ├── QUICK-REF.md      # Module quick reference
│       └── README.md         # Module documentation
└── CLAUDE.md                 # AI instruction file

Module Header Template

/**
 * ═══════════════════════════════════════════════════════════
 * MODULE: [Module Name]
 * ═══════════════════════════════════════════════════════════
 *
 * PURPOSE: [One-sentence description]
 *
 * DEPENDENCIES:
 *   - [dep1]: [reason]
 *   - [dep2]: [reason]
 *
 * EXPORTS:
 *   - [function1](params): [description]
 *   - [function2](params): [description]
 *
 * CONFIGURATION:
 *   - [CONFIG_VAR]: [description]
 *
 * ═══════════════════════════════════════════════════════════
 */

Detailed Guidelines

For complete standards, see:

• AI-Friendly Architecture Standards

AI-Optimized Format (Token-Efficient)

For AI assistants, use the YAML format file for reduced token usage:

• Base standard: ai/standards/ai-friendly-architecture.ai.yaml

.ai-context.yaml Configuration

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

analysis-hints:
  entry-points:
    - src/main.ts
    - src/index.ts
  ignore-patterns:
    - node_modules
    - 
     
   


   
   
   

Context Priority Guidelines

Priority	Content Type	Reason
1	Entry points	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 to Avoid

Anti-Pattern	Problem	Solution
Magic strings	AI can't trace constants	Typed constants with docs
Implicit routing	Hidden behavior	Explicit route mappings
Global state	Unpredictable deps	Dependency injection
Circular deps	Context confusion	Hierarchical dependencies
Monolithic files	Context overflow	Focused modules

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 info
• Add section dividers to large files

---

Configuration Detection

This skill supports project-specific configuration.

Detection Order

1. Check for existing .ai-context.yaml
2. Check for QUICK-REF.md files
3. If not found, suggest creating AI-friendly structure

First-Time Setup

If no configuration found:

1. Suggest: "This project hasn't been configured for AI collaboration. Would you like to set up an AI-friendly structure?"
2. Create .ai-context.yaml template
3. Create QUICK-REF.md in project root

---

Related Standards

• AI-Friendly Architecture - Core architecture standard
• Project Structure - Directory organization
• Documentation Structure - Documentation layering
• Anti-Hallucination - AI accuracy standards

---

Version History

Version	Date	Changes
1.0.0	2026-01-25	Initial release

---

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards