asiaostrich/ai-friendly-architecture

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.

AI Skills Hierarchy | AI 技能層級

This skill is part of a three-layer AI collaboration system:

| Layer | Skill | Question it Answers | 回答的問題 | |-------|-------|-------------------|-----------| | Behavior (Immediate) | /ai-collaboration | "How should AI respond accurately?" | 「AI 如何準確回應？」 | | Configuration (Session) | /ai-instruction-standards | "What to write in CLAUDE.md?" | 「CLAUDE.md 該寫什麼？」 | | Architecture (Long-term) | /ai-friendly-architecture (this) | "How to structure code for AI?" | 「如何讓專案對 AI 友善？」 |

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

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

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

---

Next Steps Guidance | 下一步引導

After /ai-friendly-architecture completes, the AI assistant should suggest:

AI 友善架構指南已掌握。建議下一步 / AI-friendly architecture guide understood. Suggested next steps:

• 執行 /sdd 將 AI 友善架構設計納入正式規格 ⭐ Recommended / 推薦 — 確保架構決策有規格追蹤 / Ensure architecture decisions are tracked in specs
• 建立 .ai-context.yaml 和 QUICK-REF.md — 立即實作 AI 友善結構 / Implement AI-friendly structure immediately
• 執行 /ai-instruction-standards 更新 CLAUDE.md 以反映架構配置 — 讓 AI 指令檔案與架構保持同步 / Keep AI instruction files in sync with architecture

---

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