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

Context Layers

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
    - dist
    - "*.test.ts"
  architecture-type: layered

documentation:
  quick-ref: docs/QUICK-REF.md
  detailed: docs/ARCHITECTURE.md
  examples: docs/examples/

Context Priority Guidelines

Anti-Patterns to Avoid

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

License

This skill is released under CC BY 4.0.

Source: universal-dev-standards