When is it appropriate to create a subdirectory CLAUDE.md?

Create one when a domain has non-obvious contracts, architectural decisions that affect how code evolves, or invariants that aren't clearly visible just by reading the implementation.

Why are freshness dates mandatory in these files?

Stale documentation is worse than no documentation. Using a real-time date via Bash signals to Claude when the architectural contracts were last verified as accurate.

How long should a domain-level CLAUDE.md be?

To maintain token efficiency, subdirectory files should be concise and focused, ideally remaining under 100 lines of text.

What is the main difference between top-level and subdirectory CLAUDE.md files?

Top-level files focus on 'How' to work in the codebase (commands, stack, conventions), while subdirectory files explain 'Why' a specific domain exists and its 'Contracts' with other parts of the system.

Can I use @ references to point to files in my CLAUDE.md?

No, you should simply name the files. Using @ syntax force-loads content into the AI's context window, wasting tokens. Naming them allows Claude to read them only when specifically needed.

Claude.md Architecture Guide

Name: Claude.md Architecture Guide
Author: ed3dai

byed3dai

•

Learning & Documentation

Standardizes the creation and maintenance of CLAUDE.md files to provide architectural context and project-wide conventions for AI interactions.

This skill provides a structured framework for building a hierarchy of CLAUDE.md files that bridge the gap between AI statelessness and long-term architectural intent. By distinguishing between top-level project conventions and domain-specific contracts, it ensures Claude understands not just what the code does, but why it exists and what promises it must keep. It enforces critical practices like mandatory freshness dates via shell commands and token-efficient file referencing to maintain a high-performance, accurate developer experience.

Key Features

01Enforces mandatory freshness dates using Bash integration for real-time context accuracy.

02Captures architectural intent, contracts, and invariants to prevent AI context regressions.

03Optimizes token usage by discouraging heavy file references and excessive file length.

045 GitHub stars

05Provides standardized templates for tech stacks, commands, and domain boundaries.

06Differentiates between top-level project conventions and domain-specific subdirectory guidance.

Use Cases

01Onboarding Claude to a new complex codebase with specific domain boundaries and strict architectural rules.

02Standardizing documentation across a monorepo to ensure consistent AI behavior across different modules.

03Maintaining architectural integrity during long-term feature development by documenting non-obvious invariants.

What are Skills?·How to Install

Install with 🐟 Skill.Fish

npx skillfish add ed3dai/ed3d-plugins-testing writing-claude-md-files

For use in Claude.ai and ChatGPT

Download Skill