🏗️ Long-term projects

The folder structure is the physical map of your project. It determines how modules find each other, how dependencies flow, and how new contributors (or Claude) understand the system without reading a line of code.

Projects without structure become chaotic monoliths in weeks. A well-planned folder structure from the start saves hours of refactoring later. Claude Code navigates organized projects better—less context, more precise answers.

Single Responsibility Principle applied to files and modules: every piece of code has one reason to exist and one reason to change.

Cohesive modules make it easier for Claude to understand, modify, and test isolated parts without introducing regressions. Less coupling = faster iteration.

Choose languages, runtimes, frameworks, and build tools based on explicit criteria: ecosystem, performance, ease of deployment, and Claude support.

Changing stacks in the middle of a project is costly. The right choice at the start reduces technical debt and maximizes the help Claude can provide — it knows popular stacks better.

Architecture Decision Records (ADRs) are short documents that record the decision's context, the options considered, and the choice made. CLAUDE.md is the main ADR.

Without decision documentation, Claude (and you in the future) will wonder why certain choices were made and may inadvertently undo them.

A strategy of building the functional core first and adding layers progressively—without planning a huge architecture before validating hypotheses.

Projects with Claude evolve quickly. Starting small lets you validate the design before committing effort to abstractions that may not be necessary.

Principles that keep a project healthy for months or years: asynchronous code review, living documentation, automation of repetitive tasks, and health metrics.

Most projects fail because of a lack of planned maintenance, not a lack of features. With Claude, the risk is adding code too quickly without keeping the foundation solid.

CLAUDE.md is the project's persistent instruction file. Claude reads it at the start of each session, providing context about the project, conventions, and behavioral rules.

Without CLAUDE.md, you repeat the same context every session. With it, Claude knows where it is, what it can and can't do, and how the project is structured.

Claude has no native memory between sessions. Persistent memory is built explicitly: state files, decision logs, context saved in JSON or Markdown.

Long-running projects accumulate decisions and state. Without explicit memory, each session starts from scratch, and Claude may contradict previous decisions.

Keep CLAUDE.md concise and relevant: include only what Claude needs to know now, not the project’s complete history.

A very long CLAUDE.md dilutes attention. Claude prioritizes information at the beginning of the context — critical information should appear first.

Section of CLAUDE.md that defines code standards, naming conventions, git workflow, PR rules, and communication tone that Claude should follow.

Without explicit conventions, Claude adopts its own standards — which may differ from the team's and create inconsistencies that are hard to maintain.

Guidelines on what information should go in CLAUDE.md (architecture, conventions, context) and what should never appear there (secrets, tokens, personal data).

CLAUDE.md is read and may be sent to the model. Sensitive information in it creates leakage risks — especially in projects with multiple collaborators.

How to keep CLAUDE.md up to date as the project grows: when to review it, who can edit it, and how to version changes to the instruction file.

An outdated CLAUDE.md is worse than none — Claude follows outdated instructions and may make wrong decisions based on incorrect context.

Semantic Versioning (semver): MAJOR.MINOR.PATCH — each number has a precise meaning about the type of change and compatibility.

Semantic versions communicate impact. When you ask Claude to "bump a version," it needs to know which digit to increment and why.

CHANGELOG.md file structured by version, with Added / Changed / Fixed / Removed sections. Read by humans, not machines.

The CHANGELOG is the project's diary. It lets you audit when something broke, justify changes to stakeholders, and guide Claude during maintenance sessions.

Strategies for safely reverting the project state: git revert, git reset, feature flags, deploying a previous version.

With Claude generating code quickly, rollback capability is the safety net. You need to know how to undo changes without losing valid work.

The process of improving the internal structure of code without changing its external behavior — with tests as a safety net.

Refactoring with Claude is fast and risky. Without tests, a refactor that seems safe can break workflows that weren’t visible during the session.

Well-written tests document the system’s expected behavior. They’re the most reliable spec because they have to pass—unlike docs, which become outdated.

Claude uses existing tests to understand what a module should do before modifying it. Projects with good tests get better, safer help.

Technical debt is the future cost of shortcuts taken today. It isn't always bad — but it needs to be recorded, prioritized, and paid down before it becomes unmanageable.

Projects with Claude can quickly accumulate technical debt—quickly generated code isn’t always sustainable. Periodically monitoring and paying down debt is a healthy project habit.

ClaudeOS (Hermes) is a read-only personal dashboard for people running a local AI stack. It consolidates data from Claude Code, Codex, OpenRouter, Pinecone, and Obsidian in a single interface.

It's a concrete project that applies all the principles in this learning path: layered architecture, a rigorous CLAUDE.md, versioning with a CHANGELOG, and separation of responsibilities.

The scripts/aggregate.ts file is the heart of the system: it reads ~/.claude/, Obsidian vaults, Pinecone, and OpenRouter, then generates src/data/live-data.json, which the React dashboard consumes.

This "generator script → static file → UI" pattern is an elegant architecture that separates data collection from presentation. It can be replicated in any dashboard project.

The /dream skill audits the last 24 hours of the AI stack across 8 signal buckets and writes the 4 highest-impact prescriptions in JSON. The dashboard renders these prescriptions as action cards.

It's an example of a skill with structured output (JSON) consumed by a UI — a reusable pattern for any Claude Code + dashboard integration.

ClaudeOS's CLAUDE.md defines: an onboarding greeting, critical rules (never read/write ~/.claude directly, local data, anonymization enabled, no telemetry, read-only dashboard).

This CLAUDE.md is a production-level example. It shows how to use explicit constraints to protect user data and keep the agent in its role.

The ClaudeOS CHANGELOG chronicles the project's evolution: V2.3 (Documents Gallery, 31 mai 2026) shows how each feature was added, what changed, and what was fixed.

The CHANGELOG is evidence of a mature project. Each version tells the story of maintenance—and serves as context for Claude when planning upcoming features.

Extracting replicable patterns from ClaudeOS: the scripts/src separation, CLAUDE.md with constraints, JSON as a state artifact, and CHANGELOG as a narrative.

Studying well-structured real projects is much more effective than abstract tutorials. ClaudeOS is a mental template for any long-running project with Claude Code.