mirror of https://github.com/alirezarezvani/ClaudeForge.git synced 2026-07-03 02:13:15 -04:00

Files

T

Claude e45065e8ba docs: refresh README/docs/examples + install scripts for waves 1-4

User-facing documentation drifted behind several waves of feature work
(plugin manifest, hooks, sync command, --weekly, audit skills, Karpathy
skill, CLAUDE.local.md tier, layered hook config). Refresh + fix one
real install bug. Surgical edits only — no rewrites.

README.md:
  - "What's New" block now reflects the plugin manifest, --weekly,
    InstructionsLoaded hook, AGENTS.md interop, CLAUDE.local.md tier,
    layered hook config, and the fail-closed guardian.
  - "What's Included" expanded from 5 numbered bullets to a structured
    list grouping the 5 skills (incl. three forked audit skills),
    2 slash commands, 1 agent, and 3 hook scripts.
  - Components Deep Dive: /sync-claude-md and the guardian's fail-closed
    contract now documented.
  - Project Status: 1.0.0 -> 2.1.0; Quick Stats updated to reflect
    actual component counts.
  - Acknowledgments: attribution to MIT-licensed forrestchang and
    shanraisshan source repos for adapted patterns.

docs/ARCHITECTURE.md, docs/QUICK_START.md, docs/TROUBLESHOOTING.md,
docs/INSTALLATION.md, examples/modular-setup.md, examples/integration-
examples.md:
  - Every "20-300 lines" / ">300 lines" / "exceeds 300 lines" reference
    rewritten to the actual 150-line hard cap.
  - Every ls/Remove-Item path that pointed at the legacy
    ~/.claude/commands/enhance-claude-md/ bundle now points at the
    top-level enhance-claude-md.md + sync-claude-md.md files.
  - integration-examples.md line-bounds shell guard now uses 20..150.

docs/CLAUDE.md:
  - Install-verify ls list extended with the three new audit-skill
    directories so docs match what install.sh actually creates.

install.sh + install.ps1 (REAL FIX, not just docs):
  - The three forked audit skills (claude-md-drift-audit, link-check,
    dependency-rescan) were registered in plugin.json but never copied
    by the direct-install path. Both installers now iterate over them
    after the karpathy-guidelines block, mirroring the same backup +
    nested-duplicate-cleanup pattern. Banner section and uninstall
    instructions list all 5 skills.

Verified:
  - All 5 CLAUDE.md files in this repo still <= 150 lines after edits.
  - install.sh passes bash -n syntax check.
  - Plugin manifest still resolves all 8 referenced paths on disk.
  - README invariants present: 2.1.0, --weekly, hooks/hooks.json,
    both source-repo attributions, three audit skill names.
  - Stale-claim sweep: zero "20-300" / ">300" / "exceeds 300" refs
    remain in docs/ or examples/.

2026-05-19 02:04:00 +00:00

3.6 KiB

Raw Blame History

Modular Architecture Setup

Examples of modular CLAUDE.md structure for large projects.

When to Use Modular Architecture

Full-stack projects with distinct frontend/backend
Team size > 10 developers
Single CLAUDE.md would exceed the 150-line cap
Different teams own different areas

Example: E-Commerce Platform

Project Structure:

ecommerce/
├── CLAUDE.md              # Root navigation
├── backend/
│   ├── CLAUDE.md          # API guidelines
│   └── api/
├── frontend/
│   ├── CLAUDE.md          # React guidelines
│   └── src/
├── mobile/
│   ├── CLAUDE.md          # React Native guidelines
│   └── app/
└── database/
    ├── CLAUDE.md          # Schema guidelines
    └── migrations/

Setup:

mkdir -p ecommerce/{backend,frontend,mobile,database}
cd ecommerce

# Create basic files for detection
echo '{"dependencies":{"express":""}}' > backend/package.json
echo '{"dependencies":{"react":""}}' > frontend/package.json
echo '{"dependencies":{"react-native":""}}' > mobile/package.json

Run:

/enhance-claude-md

"Use modular architecture for this full-stack e-commerce platform"

Output:

CLAUDE.md - 95 lines (navigation)
backend/CLAUDE.md - 180 lines (API, auth, payments)
frontend/CLAUDE.md - 165 lines (components, state, cart)
mobile/CLAUDE.md - 145 lines (screens, navigation, offline)
database/CLAUDE.md - 120 lines (schema, migrations, queries)

Content:

# CLAUDE.md

Quick navigation hub for this project.

## Quick Navigation

- [Backend API Guidelines](backend/CLAUDE.md)
- [Frontend React Guidelines](frontend/CLAUDE.md)
- [Mobile App Guidelines](mobile/CLAUDE.md)
- [Database Operations](database/CLAUDE.md)

## Core Principles

1. API-first development
2. Mobile-responsive design
3. Database integrity
4. Comprehensive testing

## Project Structure

[ASCII tree diagram]


## Common Commands

```bash
# Backend
cd backend && npm run dev

# Frontend
cd frontend && npm start

# Mobile
cd mobile && npm run ios


---

## Context-Specific Files

### backend/CLAUDE.md

**Focus:**
- API endpoints design (REST/GraphQL)
- Authentication & authorization
- Database queries and optimization
- Error handling patterns
- Testing strategies (unit, integration)

### frontend/CLAUDE.md

**Focus:**
- Component architecture
- State management
- Routing and navigation
- Performance optimization
- Accessibility standards

### mobile/CLAUDE.md

**Focus:**
- Screen layouts
- Native features (camera, GPS, etc.)
- Offline functionality
- Platform-specific patterns (iOS/Android)
- App store deployment

### database/CLAUDE.md

**Focus:**
- Schema design
- Migration procedures
- Query optimization
- Backup strategies
- Data integrity rules

---

## Benefits

✅ **Separation of Concerns:** Each area has focused guidelines
✅ **Team Ownership:** Different teams manage their files
✅ **Maintainability:** Easier to update specific areas
✅ **Scalability:** Add new areas without bloat
✅ **Readability:** Each file stays under 200 lines

---

## Maintenance

**Guardian Agent updates all files:**

New backend dependency added

✅ backend/CLAUDE.md updated: Tech Stack section

New frontend component pattern

✅ frontend/CLAUDE.md updated: Component Guidelines

Database schema change

✅ database/CLAUDE.md updated: Schema Documentation


---

See also:
- [basic-usage.md](basic-usage.md) - Simple projects
- [integration-examples.md](integration-examples.md) - CI/CD

3.6 KiB Raw Blame History