Directory Structure

Overview

Claude Code loads .claude/ from TWO locations:

1. Home directory (~/.claude/) - always loaded
2. Current working directory ({cwd}/.claude/) - if exists

Important: Claude does NOT recursively scan subdirectories. If you run claude from ~/Projects/myapp/, it will NOT find ~/Projects/.claude/.

Recommended Structure

~/                                      # Home directory
├── .gitignore                          # Ignores project-specific components
│
├── .claude/                            # Faion Network Framework (git repo)
│   ├── CLAUDE.md                       # Global instructions
│   ├── settings.json                   # Global settings
│   │
│   ├── skills/                         # ALL skills (global + project)
│   │   ├── faion/            # Global: umbrella knowledge (52 domain knowledge bases, tier-partitioned)
│   │   │   └── knowledge/              #   ├── free/ (8), solo/ (13), pro/ (24), geek/ (7)
│   │   │                               #   each tier → groups (dev/, ai/, infra/, product/, pm/, ba/, ux/, marketing/, research/, comms/, sdd/)
│   │   ├── faion-brainstorm/           # Global: multi-agent brainstorm
│   │   ├── faion-feature-executor/     # Global: SDD feature executor
│   │   ├── faion-sdd-execution/        # Global: SDD quality gates + reflexion
│   │   ├── faion-improver/             # Global: session-based improvement
│   │   └── {project}-*/                # Project: gitignored
│   │
│   ├── agents/                         # ALL agents (global + project)
│   │   ├── faion-*-agent.md            # Global: committed
│   │   └── myapp-*-agent.md            # Project: gitignored
│   │
│   ├── commands/                       # ALL commands
│   │   ├── commit.md                   # Global: committed
│   │   └── myapp-*.md                  # Project: gitignored
│   │
│   ├── scripts/hooks/                  # ALL hooks
│   │   ├── faion-*-hook.*              # Global: committed
│   │   └── myapp-*-hook.*              # Project: gitignored
│   │
│   └── docs/                           # Framework documentation
│       └── directory-structure.md      # This file
│
└── Projects/                           # Projects folder
    │
    ├── myapp/                          # Single-repo project
    │   ├── CLAUDE.md                   # Project instructions
    │   ├── src/                        # Source code
    │   ├── .git/                       # Git repository
    │   └── .aidocs/                    # SDD documentation
    │       ├── constitution.md
    │       ├── roadmap.md
    │       ├── product_docs/
    │       ├── backlog/
    │       │   ├── feature-001-auth/
    │       │   └── TASK-0001-setup.md
    │       ├── todo/
    │       ├── in-progress/
    │       └── done/
    │
    └── bigapp/                         # Multi-repo project
        ├── CLAUDE.md                   # Project overview
        ├── bigapp-fe/                  # Frontend repo
        │   ├── .git/
        │   └── src/
        ├── bigapp-be/                  # Backend repo
        │   ├── .git/
        │   └── src/
        └── .aidocs/                    # Shared SDD docs for all repos
            ├── constitution.md         # Covers FE + BE
            ├── roadmap.md
            ├── product_docs/
            ├── backlog/
            │   ├── feature-001-auth/   # May touch FE + BE
            │   └── TASK-0001-api.md
            ├── todo/
            ├── in-progress/
            └── done/

Key Points

1. Single .claude/ directory in ~/ contains everything
2. Global components (faion-*) are committed to faion-network repo
3. Project components ({project}-*) are gitignored
4. Project CLAUDE.md lives in project root (not in .claude)
5. .aidocs/ location:
   • Single repo: Inside repo root (alongside src/)
   • Multi-repo: Parent level (alongside repo folders)

Why This Structure?

Claude Code always finds ~/.claude/ regardless of where you run it:

cd ~/Projects/myapp && claude    # Loads ~/.claude/ ✓
cd ~/Projects/another && claude  # Loads ~/.claude/ ✓
cd ~ && claude                   # Loads ~/.claude/ ✓

All skills/agents are always available, project-specific ones just need gitignore.

.aidocs/ Placement Rules

Decision tree:

Does the project have multiple repos?
├─ NO (single repo)
│  └─ Place .aidocs/ INSIDE repo root
│     Example: myapp/.aidocs/
│
└─ YES (multiple repos: FE, BE, mobile, etc.)
   └─ Place .aidocs/ at PARENT level (alongside repos)
      Example: myapp/.aidocs/ + myapp/myapp-fe/ + myapp/myapp-be/
<<<<<<< HEAD
=======

Why?

• Single repo: .aidocs/ is versioned with code, easier to clone
• Multi-repo: .aidocs/ is shared, avoids duplication, single source of truth

Examples:

Project Structure	.aidocs/ Location	Reason
myapp/ (monorepo)	myapp/.aidocs/	Single repo
bigapp/bigapp-fe/ + bigapp/bigapp-be/	bigapp/.aidocs/	Multi-repo, shared docs
faion-net/ (Gatsby)	faion-net/.aidocs/	Single repo
scanmecard/scanmecard-web/ + scanmecard/scanmecard-api/	scanmecard/.aidocs/	Multi-repo

.aidocs Structure

SDD (Specification-Driven Development) documentation lives in project's .aidocs/:

.aidocs/
├── constitution.md                 # Immutable project principles
│   - Tech stack (for ALL repos in multi-repo setup)
│   - Code standards (linters, formatters)
│   - Testing requirements
│   - Git conventions
│   - Multi-repo: describes FE, BE, and shared standards
│
├── roadmap.md                      # High-level project roadmap
│
├── product_docs/                   # Product documentation
│   ├── prd.md                      # Product Requirements
│   ├── user-personas.md            # Target users
│   └── competitive-analysis.md     # Market research
│
├── backlog/                        # Ideas, not prioritized
│   ├── feature-001-auth/           # Feature folder
│   │   ├── spec.md                 # Functional requirements (FR-X)
│   │   ├── design.md               # Architecture decisions (AD-X)
│   │   └── implementation-plan.md  # Task breakdown
│   └── TASK-0001-setup.md          # Standalone task file
│
├── todo/                           # Specified, ready to implement
│   ├── feature-002-payments/
│   └── TASK-0005-database.md
│
├── in-progress/                    # Currently executing
│   ├── feature-003-dashboard/
│   └── TASK-0010-api.md
│
└── done/                           # Completed
    ├── feature-000-init/
    └── TASK-0000-scaffold.md
>>>>>>> claude

Why?

• Single repo: .aidocs/ is versioned with code, easier to clone
• Multi-repo: .aidocs/ is shared, avoids duplication, single source of truth

Examples:

Project Structure	.aidocs/ Location	Reason
myapp/ (monorepo)	myapp/.aidocs/	Single repo
bigapp/bigapp-fe/ + bigapp/bigapp-be/	bigapp/.aidocs/	Multi-repo, shared docs
faion-net/ (Gatsby)	faion-net/.aidocs/	Single repo
scanmecard/scanmecard-web/ + scanmecard/scanmecard-api/	scanmecard/.aidocs/	Multi-repo

.aidocs Structure

SDD (Specification-Driven Development) documentation lives in project's .aidocs/:

.aidocs/
├── constitution.md                 # Immutable project principles
│   - Tech stack (for ALL repos in multi-repo setup)
│   - Code standards (linters, formatters)
│   - Testing requirements
│   - Git conventions
│   - Multi-repo: describes FE, BE, and shared standards
│
├── roadmap.md                      # High-level project roadmap
│   - Feature timeline and phases
│   - Release schedule
│   - Success metrics and goals
│   - Platform metrics
│
├── product_docs/                   # Product planning & GTM
│   ├── article-lists/              # Editorial calendar
│   │   - Content planning
│   │   - Publishing schedule
│   │
│   ├── gtm-manifest/               # Go-to-market strategy
│   │   - Launch strategy
│   │   - Marketing channels
│   │   - Distribution plan
│   │
│   ├── seo/                        # SEO keywords & strategy
│   │   - Keyword research
│   │   - Content optimization
│   │   - Search strategy
│   │
│   └── [other product docs]        # PRD, personas, competitive analysis
│
├── content/                        # Content drafts & planning
│   └── articles/                   # Article drafts (MDX/Markdown)
│       - Blog posts
│       - Tutorials
│       - Documentation
│
├── improvements/                   # Feature proposals & enhancements
│   ├── README.md                   # Improvement tracking overview
│   └── AI-NNN-*.md                 # Individual improvement suggestions
│
├── backlog/                        # Ideas, ready for grooming
│   ├── feature-NNN-name/           # Feature folder
│   │   ├── README.md               # Feature overview & context
│   │   ├── spec.md                 # What to build (requirements, success criteria)
│   │   ├── design.md               # How to build (architecture, API contracts)
│   │   └── implementation-plan.md  # Task breakdown, dependencies, token estimates
│   └── TASK-NNNN-title.md          # Standalone task file
│
├── todo/                           # Specified, ready to execute
│   ├── feature-NNN-name/           # Feature folder (all docs ready)
│   └── TASK-NNNN-title.md          # Ready task
│
├── in-progress/                    # Currently executing
│   ├── feature-NNN-name/           # Feature being implemented
│   └── TASK-NNNN-title.md          # Task in progress
│
└── done/                           # Completed and verified
    ├── feature-NNN-name/           # Completed feature (archive)
    └── TASK-NNNN-title.md          # Completed task

Documentation Types

Document	Purpose	Content
constitution.md	Project foundation	Tech stack, architecture decisions (ADRs), coding standards, multi-repo setup
roadmap.md	Strategic planning	Feature timeline, release schedule, success metrics, platform KPIs
spec.md	Requirements	What to build, functional requirements (FR-X), success criteria, acceptance tests
design.md	Architecture	How to build, technical decisions (AD-X), API contracts, data models, diagrams
implementation-plan.md	Execution plan	Task breakdown with dependencies, complexity estimates, token budgets
README.md	Feature overview	Context, motivation, high-level summary (in feature folders)

Folder Purposes

Folder	Purpose
product_docs/	Product strategy, GTM planning, content calendar, SEO strategy
content/	Article drafts, blog posts, tutorials (MDX/Markdown)
improvements/	Feature enhancement proposals, suggestions from AI analysis
backlog/	Features in grooming phase, not yet ready for implementation
todo/	Fully specified features, ready to execute (spec/design/plan complete)
in-progress/	Currently executing features/tasks
done/	Completed and verified features/tasks (archive)

Lifecycle

backlog/ → todo/ → in-progress/ → done/

Status	Description
backlog/	Ideas, not yet specified
todo/	Specified (spec.md exists), ready to implement
in-progress/	Currently being implemented
done/	Completed and verified

Feature Movement:

• Features (folders feature-NNN-name/) move with their tasks
• Tasks (TASK-NNNN-title.md) can move independently
• Both follow the same lifecycle path

Real-World Example: faion-net

Multi-repository project with shared .aidocs/ structure:

~/Projects/faion-net/
├── CLAUDE.md                       # Project overview
├── .aidocs/                        # Shared SDD docs (ALL repos)
│   ├── constitution.md             # Tech stack (Gatsby + Django + Go)
│   ├── roadmap.md                  # Feature roadmap & metrics
│   │
│   ├── product_docs/               # Product & GTM
│   │   ├── article-lists/          # Editorial calendar
│   │   ├── gtm-manifest/           # Marketing strategy
│   │   └── seo/                    # SEO keywords
│   │
│   ├── content/                    # Content planning
│   │   └── articles/               # Blog post drafts
│   │
│   ├── improvements/               # Feature proposals
│   │   ├── README.md
│   │   └── AI-001-*.md
│   │
│   ├── backlog/
│   │   └── feature-026-knowledge-infrastructure/
│   │       ├── README.md
│   │       ├── spec.md
│   │       ├── design.md
│   │       └── implementation-plan.md
│   │
│   ├── todo/
│   │   └── feature-024-starter-kits/
│   │       ├── spec.md
│   │       ├── design.md
│   │       ├── implementation-plan.md
│   │       └── TASK-SK-*.md        # 5 tasks
│   │
│   └── done/
│       └── feature-025-cli-tool/
│           ├── spec.md
│           ├── design.md
│           ├── implementation-plan.md
│           └── TASK-CLI-*.md       # 7 completed tasks
│
├── faion-net-fe/                   # Frontend repo (Gatsby 5)
│   ├── .git/
│   ├── CLAUDE.md                   # FE-specific instructions
│   ├── content/                    # 502 MDX methodologies
│   └── src/
│
├── faion-net-be/                   # Backend repo (Django 5)
│   ├── .git/
│   ├── CLAUDE.md                   # BE-specific instructions
│   ├── apps/                       # 10 Django apps
│   └── manage.py
│
├── faion-cli/                      # CLI tool repo (Go, DEPRECATED — replaced by Python Agent SDK pipelines in faion-network/skills/)
│   ├── .git/
│   ├── cmd/                        # Commands (legacy)
│   └── tui/                        # Bubble Tea TUI (legacy)
│
└── faion-network-storybook/        # Component library (React)
    ├── .git/
    └── stories/                    # 62 components

Key points:

• One .aidocs/ folder for ALL repositories
• constitution.md covers tech decisions for FE, BE, CLI, Storybook
• Features can touch multiple repos (e.g., Starter Kits = BE API + CLI download)
• Completed Feature 025 (CLI Tool) → moved from todo/ to done/ with all tasks
• Active Feature 024 (Starter Kits) → in todo/, executing TASK-SK-001

Naming Conventions

Global (Faion Network)

Component	Pattern	Example
Skill (orchestrator)	faion-net	faion-net
Skill (role-based)	faion-{role}	faion-software-developer, faion-ux-ui-designer
Skill (process)	faion-{process}	faion-sdd, faion-feature-executor
Agent	faion-{name}-agent	faion-task-YOLO-executor-opus-agent
Hook	faion-{event}-{purpose}-hook.{ext}	faion-pre-bash-security-hook.py
Command	{verb} (no prefix)	commit, deploy

Project-Specific

Component	Pattern	Example
Skill	{project}-{name}	myapp-auth, myapp-deploy
Agent	{project}-{name}-agent	myapp-deploy-agent
Hook	{project}-{event}-{purpose}-hook.{ext}	myapp-pre-bash-lint-hook.sh
Command	{project}-{action}	myapp-build

Features & Tasks

Component	Pattern	Example
Feature folder	feature-{NNN}-{name}	feature-001-auth, feature-025-dashboard
Task file	TASK-{NNNN}-{title}.md	TASK-0001-user-model.md, TASK-0150-api-endpoint.md

Gitignore Setup

Add .gitignore at the same level as .claude/ (sibling, not inside):

~/                          # or ~/Projects/
├── .gitignore              # ← HERE (sibling of .claude/)
└── .claude/                # Framework

Content:

# Project-specific Claude components (not committed to faion-network)
.claude/skills/*
!.claude/skills/faion-*/

.claude/agents/*-*-agent.md
!.claude/agents/faion-*-agent.md

.claude/commands/*-*.md
!.claude/commands/faion-*.md

.claude/scripts/hooks/*-*-hook.*
!.claude/scripts/hooks/faion-*-hook.*

# Local settings
.claude/settings.local.json

Simpler alternative (if you know project names):

# Project-specific (myapp)
.claude/skills/myapp-*/
.claude/agents/myapp-*.md
.claude/commands/myapp-*.md
.claude/scripts/hooks/myapp-*

# Local settings
.claude/settings.local.json

Quick Setup

New Single-Repo Project

# Create project directory
mkdir -p ~/Projects/myapp
cd ~/Projects/myapp

# Initialize git
git init

# Create project CLAUDE.md
cat > CLAUDE.md << 'EOF'
# MyApp - Claude Instructions

## Project
- Name: MyApp
- Tech: Python 3.11, Django 5.x
- Build: `make build`
- Test: `make test`

## References
- [Directory Structure](~/.claude/docs/directory-structure.md)
EOF

# Create .aidocs structure (inside repo)
mkdir -p .aidocs/{product_docs,backlog,todo,in-progress,done}

New Multi-Repo Project

# Create project parent directory
mkdir -p ~/Projects/bigapp
cd ~/Projects/bigapp

# Create project CLAUDE.md
cat > CLAUDE.md << 'EOF'
# BigApp - Claude Instructions

## Project
- Name: BigApp
- Repos: bigapp-fe (React), bigapp-be (Django)
- Documentation: .aidocs/ (shared)

## Repositories
- **Frontend:** ./bigapp-fe/ - React + Vite
- **Backend:** ./bigapp-be/ - Django REST

## References
- [Directory Structure](~/.claude/docs/directory-structure.md)
EOF

# Create .aidocs structure (parent level, shared)
mkdir -p .aidocs/{product_docs,backlog,todo,in-progress,done}

# Clone or create repos
git clone <frontend-repo-url> bigapp-fe
git clone <backend-repo-url> bigapp-be
# OR
mkdir bigapp-fe && cd bigapp-fe && git init && cd ..
mkdir bigapp-be && cd bigapp-be && git init && cd ..

# Add to .gitignore (same level as .claude/)
grep -q "myapp-" .gitignore 2>/dev/null || cat >> .gitignore << 'EOF'

# Project: myapp
.claude/skills/myapp-*/
.claude/agents/myapp-*.md
.claude/commands/myapp-*.md
.claude/scripts/hooks/myapp-*
EOF

Create Project Skill

# Create in ~/.claude/skills/ (not in project!)
mkdir -p ~/.claude/skills/myapp-auth-skill
cat > ~/.claude/skills/myapp-auth-skill/SKILL.md << 'EOF'
---
name: myapp-auth-skill
description: "Authentication logic for MyApp"
user-invocable: false
---

# MyApp Auth Skill

...

---
*Created with [faion.net](https://faion.net) framework*
EOF

# Ensure it's gitignored (run from directory containing .claude/)
grep -q "myapp-" .gitignore 2>/dev/null || echo ".claude/skills/myapp-*/" >> .gitignore

---

Part of Faion Network framework