Claude Code + GitHub: the 8-folder setup we use on every build
One repo. Every team member linked. Same outputs, regardless of who runs it.
Most Claude Code setups start well. One CLAUDE.md file, clear instructions, and Claude produces exactly what you need. Then the file grows. Rules, domain knowledge, session state, agent definitions. All in one place. Claude starts behaving inconsistently across sessions. The moment someone else picks up the project, they have to re-explain everything from scratch.
This is not a prompt quality problem. It is a structure problem.
Ninjabot delivers ready-to-deploy sales AI and automation tools that allows business operators to stop doing busywork and start managing leverage.
🔮 Today’s insights
Gartner: 40% of AI agent projects will fail by 2027
Gartner published in it’s AI agent report that 42% of organizations plan to deploy agents in the next 12 months. 40% will fail. After hundreds of implementations I can tell you the failure isn’t the technology. It’s the sequence. Agents get built before processes are documented, before access scope is defined, before teams understand what they’re supposed to trust. The Gartner number will land exactly as predicted because most teams are skipping the same two steps.
LinkedIn kills engagement pods, and the algorithm now punishes them structurally
LinkedIn VP Oscar Rodriguez confirmed: engagement pod groups removed, automated commenting suppressed, Top Voices status at risk for accounts caught gaming signals. The important part isn’t the enforcement. It’s the reason. LinkedIn replaced its feed ranking with an LLM-based system that reads content semantically and matches it to users by genuine interest. Manufactured engagement actively pollutes that signal. The algorithm has become structurally hostile to the approach, not just policy-hostile. Specific content written for real operators now has a mechanical advantage it didn’t have six months ago.
Vertical AI is replacing Vertical SaaS as the agency model
The shift is simple but the implications are significant. Vertical SaaS sells software seats. Clients compare them to Make.com at €9/month and n8n for free. Vertical AI sells the outcome of specific labor: invoices chased, leads qualified, onboarding completed. The pricing comparison changes entirely. A human invoice coordinator costs €2,500 to €4,000/month. An automated system doing the same work runs €400 to €800/month.
💡 The Claude project structural decision most operators skip
The fix is one decision, made once at the start of any project.
Separate what Claude knows from how it behaves from where it is in a workflow right now.
These are three different types of information. They change at different rates, serve different purposes, and break differently when mixed. One file containing all three means Claude re-interprets everything as the same type of instruction every session. That is why outputs drift.
Here is the model:
rules/
How should Claude behave? Behavioral instructions: code style, brand voice, API conventions, QA standards. Slow-changing. Committed to git. Applied across every task.
context/
What should Claude know? Domain knowledge: audience definitions, topic taxonomy, approved sources, brand terminology. Not instructions on how to act. Facts about the world of the project. Updated when the domain evolves.
memory/
Where is the workflow right now? Runtime state only. Where the pipeline is, what has been completed, what comes next. The only folder that changes between runs. Gitignored.
Everything else (schemas/, commands/, agents/, skills/, protocols/) layers on top of this foundation. But these three folders resolve most of the consistency problem.
What the setup actually looks like
The .claude/ folder sits at your project root, alongside CLAUDE.md. CLAUDE.md itself should fit on one screen. It points to the relevant subfolders for the task, it is not where the content lives.
We have run this setup on every Ninjabot client build for the past six months. The workflow is always the same: create a Claude Project, then attach the GitHub repo in the project’s file settings. The repo holds the full .claude/ folder structure. Claude Code updates it during active sessions. Manual edits go directly to the repo between sessions. Every team member links their own Claude Project to the same repo. One committed folder structure becomes the team’s shared context, available to Claude in every session, for everyone. One day to scaffold. Day one behavior matches day ninety, regardless of who is running it.
One step most people miss: after any update to the repo, go to your Claude Project settings and sync it. The project does not pull changes automatically. If you skip the sync, Claude is working from a stale version of your rules and context, and you will not know until the outputs start drifting again.
Start with three folders:
rules/
One file per behavioral domain. Code style, brand voice, API conventions. Anything that tells Claude how to act.
context/
One file per knowledge domain. Audience, topic taxonomy, approved sources. Anything Claude needs to know to do good work on this project.
memory/
Leave empty until your first agent run. One state.json. One run-log.md. Nothing else.
Add settings.json at the .claude/ root to define which tools Claude Code can use and which paths it can write to. Add settings.env.json to separate behavior across dev, staging, and production.
Four places this breaks
Rules stuffed with context
Domain facts land in rules/ because they feel like instructions. They are not. Fix: before adding anything to rules/, ask: does this tell Claude how to act, or what to know? If the latter, it belongs in context/.
Memory treated as permanent
State.json grows to include audience definitions and brand rules. Then it gets gitignored and lost. Fix: memory/ is for workflow position only. Anything that should survive a session reset lives in context/.
CLAUDE.md that does not delegate
Adding subfolders but keeping all instructions in CLAUDE.md defeats the separation. CLAUDE.md becomes the same 400-line problem in a different location. Fix: CLAUDE.md should be an entry point, not a content file. If it does not fit on one screen, the content belongs in a subfolder.
Repo updated, project not synced
The repo is updated, new context file, revised rule, updated state, but the Claude Project still points to the previous version. Claude behaves as if nothing changed. Fix: every time the repo is updated, open the Claude Project settings and sync. Make it part of the same commit habit as the update itself.
🔧 Tools & Resources
These three tools cover the full setup: the agent that reads the folder, the IDE that mirrors the concept, and the knowledge layer that keeps context/ human-readable between sessions.
Claude Code: reads CLAUDE.md and the .claude/ folder at session start, responds to slash commands, and updates the repo during active sessions. Works best when the folder structure is already clean: a 400-line CLAUDE.md gives it the same problems you started with. Free tier available.
Cursor: IDE with a .cursorrules file at project root, the same separation concept as .claude/, but flatter and simpler. If your team uses Cursor alongside Claude Code, keep the rules consistent across both files or they will contradict each other mid-session. Hobby plan free. Pro $20/month.
Obsidian + Git plugin: markdown knowledge base committed to git and attached to Claude Projects as the context/ layer. Human-readable, version-controlled, and editable without touching a terminal. Not the right choice if your context files need structured schemas, Obsidian is prose-first. Free for personal use. Sync via git plugin: free.
📥 Steal my template
I turned this architecture into a ready-to-use template: CLAUDE.md, all eight subfolders, starter settings files, and a SKILL.md that scaffolds the whole thing with Claude Code. Clone it, use the template, or drop just the SKILL.md into any existing project.
Three questions. Eight folders. One structural separation.
Most of the inconsistency people experience with Claude Code is not in the model. It is in the mixing. Separate the three types of information. Commit the structure to git. The consistency follows.
Build with calm,
P.S. On my LinkedIn I share short tech updates and early previews of topics before they become newsletter issues.