The CLAUDE.md Paradox: When Your AI Framework Needs to Protect User Preferences
The CLAUDE.md Paradox: When Your AI Framework Needs to Protect User Preferences
How we spent a day working ON BOS-AI instead of IN it - and why that matters
If you're building products with AI assistants like Claude, you've probably encountered configuration files that customize how the AI behaves. Today I want to share a fascinating architectural problem we solved in BOS-AI - one that might save you hours if you're building any kind of framework or library for AI-assisted development.
But first, let me explain what BOS-AI actually is.
What is BOS-AI?
BOS-AI (Business Operating System - AI) is an open-source framework that turns Claude into a business operations partner. Think of it as having 30 specialized AI agents - for marketing, sales, customer service, finance, and strategy - all coordinated through simple commands.
Instead of asking Claude generic questions, you run commands like:
/coord optimize- Analyzes your business and finds the biggest opportunity/coord marketing-system-setup- Creates a complete marketing framework in 4-5 hours/meeting @brand-strategy "positioning for SaaS"- Has a focused strategy session with the brand specialist
The key insight behind BOS-AI is the Business Chassis formula:
Profit = Prospects × Lead Conversion × Client Conversion × Average Spend × Transaction Frequency × Margin
Improve each multiplier by just 10%, and you get 77% more profit. BOS-AI systematically optimizes all six multipliers.
But today's story isn't about what BOS-AI does - it's about a gnarly architectural problem we had to solve.
The Problem: A Configuration Paradox
Claude Code (the CLI tool that powers this) uses a file called CLAUDE.md to customize how Claude behaves. When you install BOS-AI into your project, it deploys its own CLAUDE.md with all the business agent documentation and commands.
Here's where it gets interesting:
BOS-AI itself is built using another framework called AGENT-11 (our technical development framework). AGENT-11 also has its own CLAUDE.md with development instructions.
And users who install BOS-AI might want their own personal preferences in CLAUDE.md too.
See the conflict?
AGENT-11 deploys to → BOS-AI's .claude/CLAUDE.md (overwrites our dev instructions)
BOS-AI deploys to → User's .claude/CLAUDE.md (overwrites their preferences)
Every time a framework updates, someone's configuration gets blown away.
The Solution: The /library/ Folder Pattern
After exploring several approaches, we landed on an elegant solution: separate deployable content from project-specific content.
Here's the new architecture:
Library Repo
├── /library/
│ └── CLAUDE.md ← DEPLOYABLE (goes to user's .claude/CLAUDE.md)
│
├── /.claude/
│ └── CLAUDE.md ← Development framework (never deployed)
│
└── /CLAUDE.md ← Personal preferences (never deployed)
The key insight: what you deploy should live in a different place than what you use locally.
When a user runs our install script, it downloads from /library/CLAUDE.md and puts it in their .claude/CLAUDE.md. Their root /CLAUDE.md - where they keep personal preferences - is never touched.
┌─────────────────────────────────────────────────────────────────┐
│ USER'S PROJECT │
├─────────────────────────────────────────────────────────────────┤
│ │
│ /CLAUDE.md ← User's personal preferences │
│ ┌─────────────────────┐ (never touched by updates) │
│ │ # My Project │ │
│ │ - My coding style │ ┌──────────────────────┐ │
│ │ - My preferences │ │ │ │
│ └─────────┬───────────┘ │ Claude Code │ │
│ │ │ reads BOTH │ │
│ └──────────────────►│ │ │
│ │ Combined context │ │
│ ┌──────────────────►│ │ │
│ ┌─────────┴───────────┐ └──────────────────────┘ │
│ │ # BOS-AI System │ │
│ │ - Commands │ ← Updated on reinstall │
│ │ - Agent docs │ (user prefs untouched) │
│ └─────────────────────┘ │
│ .claude/CLAUDE.md │
└─────────────────────────────────────────────────────────────────┘
Claude Code reads both files and combines the context. Users get the library functionality AND keep their personal preferences through updates.
Other Improvements We Made Today
While we were in "work ON the framework" mode, we tackled several other issues:
README Restructure (81% Reduction)
Our README had become a monster. We applied progressive disclosure:
- Quick start command right at the top
- Essential concepts in scannable tables
- Details moved to linked documentation
The README went from overwhelming to inviting.
CLAUDE.md Performance Fix (83% Reduction)
We got a warning: CLAUDE.md exceeded the 40K character performance threshold. The file was 44KB and 1,157 lines.
Solution: ruthless condensation. We moved FAQ, troubleshooting, and detailed explanations to separate reference documents. The result: 7.4KB and 241 lines. Same information, better organization.
PRD v3.1 System
We launched an enhanced Product Requirements Document system with what we call the "System Skeleton" approach:
- Machine-parsable sections that developers can extract programmatically
- Auto mode (Claude drives) vs Engaged mode (collaborative)
- Design Playbook for technical preferences
- Default configurations for common scenarios
The goal: a PRD that actually helps developers build, not just describes what to build.
Legacy File Cleanup
When we renamed files (like Product Requirements Document (PRD) Creation SOP.md to just PRD Creation SOP.md), the old files would persist in deployed projects. Users would have both versions, causing confusion.
Fix: delete the target folder before copying new files. Simple, but we had to think about it.
Removing Dead Code
We found a deployment script (deploy-bos-ai.sh) that had no valid use case. It was designed to run from the BOS-AI repo and deploy to the same directory - which would overwrite our development framework with the business framework. Exactly what we warn users NOT to do.
Deleted.
The Meta Lesson: Working ON vs Working IN
There's a saying in business: spend time working ON your business, not just IN your business.
The same applies to tools and frameworks.
Today we made zero progress on any business project. We didn't create any marketing plans, sales frameworks, or PRDs for products. By one measure, it was an unproductive day.
But everything we built today compounds:
- Every future user gets a clearer README
- Every future PRD follows a better structure
- Every library update no longer destroys personal settings
- Every developer understands the architecture faster
If you're building with AI, consider: when was the last time you improved your workflow itself rather than just using it?
If You're Building AI Frameworks
Here are the patterns that might help you:
-
The /library/ pattern: Separate deployable content from local configuration. Your users will thank you when updates don't destroy their customizations.
-
Progressive disclosure: Don't put everything in one file. Quick start → Core concepts → Detailed reference. Let people dig deeper when they need to.
-
Performance budgets: Large configuration files slow down AI assistants. Measure and optimize.
-
Clean deployments: When you rename or remove files, make sure your deployment process removes the old versions.
-
Document the architecture: Diagrams showing what goes where save hours of confusion.
Try BOS-AI
If you're a founder or business operator looking to systematize your operations with AI, check out BOS-AI:
mkdir ~/my-business && cd ~/my-business && git init
curl -fsSL https://raw.githubusercontent.com/TheWayWithin/BOS-AI/main/deployment/scripts/install.sh | bash -s full
claude code .
/coord optimize
It's open source and free. The Business Chassis formula alone is worth understanding - the multiplication effect is real.
Building BOS-AI in public. Follow along for more lessons from the intersection of AI and business operations.
Today's commits: 9 total, ~2,500 lines removed through condensation, 1 new architectural pattern, 3 diagrams added.