agentleFS
Sign inStart free
lglucaslglucas/ai-dev-operating-system/CLAUDE.md

ai-dev-operating-system

CLAUDE.md12 starsChanged 45 days agoMITView on GitHub

This file defines how Claude Code and other AI coding agents should behave inside this repository. The purpose of this repo is to provide a day-zero operating system for AI-assisted SaaS development: rules, agents, skills, commands, documentation layers, sprint system, changelog discipline, session logs, security gates, and prototype workflows. Listed in the order the wizard produces them: The canonical wizard is WIZARD.md. It runs in 5 phases: Do not simplify it. Do not skip phases. Phase 3 runs before Phase…

  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

10 rules. About 0 are common, 8 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈8

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not code before context.

    line 11
  2. Very specific:

    Use START-HERE.md and WIZARD.md for new projects.

    line 12
  3. Distinctive:

    Keep documentation layers separate.

    line 13
  4. Distinctive:

    Use multi-agent review when relevant.

    line 16
  5. Distinctive:

    No invented facts in market, competitor, legal, pricing, or regulatory claims.

    line 17
  6. Distinctive:

    Use separation of concerns and keep code files under 200 lines where practical.

    line 18
  7. Distinctive:

    Use stable dependencies by default.

    line 20
  8. Distinctive:

    Do not simplify it. Do not skip phases.

    line 57
  9. Distinctive:

    Do not move to code before all of Phase 1–4 is complete and approved.

    line 61
  10. Very specific:

    Run the ones your change touches before calling it done.

    line 74

≈ “Common” is an estimate: at least 1 in 5 of the 26,980 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

CLAUDE.md — AI Dev Operating System

This file defines how Claude Code and other AI coding agents should behave inside this repository.

The purpose of this repo is to provide a day-zero operating system for AI-assisted SaaS development: rules, agents, skills, commands, documentation layers, sprint system, changelog discipline, session logs, security gates, and prototype workflows.

Golden rules

  1. Do not code before context.
  2. Use START-HERE.md and WIZARD.md for new projects. Prototype (Phase 3) before specifying (Phase 4).
  3. Keep documentation layers separate.
  4. Preserve decision memory in session-log/.
  5. Human review is mandatory for BP v0.0.1 before BP v0.0.2.
  6. Use multi-agent review when relevant.
  7. No invented facts in market, competitor, legal, pricing, or regulatory claims.
  8. Use separation of concerns and keep code files under 200 lines where practical.
  9. Generated code files should include purpose/version/sprint headers.
  10. Use stable dependencies by default; avoid alpha/beta unless explicitly accepted.

Required generated artifacts for a new project

Listed in the order the wizard produces them:

knowledge-base/README.md                (Phase 2)
docs/business/BUSINESS-PLAN.md          (Phase 2)
docs/business/PITCH.md                  (Phase 2)
prototype-lab/README.md                 (Phase 3)
docs/product/DESIGN-DIRECTION.md        (Phase 3)
docs/product/PRODUCT-BRIEF.md           (Phase 4)
docs/technical/TECHNICAL-PLAN.md        (Phase 4)
docs/SPRINTS.md                         (Phase 4)
CODEMAP.md                              (Phase 5, generated from the code)
CHANGELOG.md
session-log/INDEX.md
session-log/YYYY-MM-DD-project-genesis.md

Project Genesis Wizard

The canonical wizard is WIZARD.md. It runs in 5 phases:

PhaseNameProduces
1Largadadetached repo, project intro
2Ideaçãoresearch, red team, BP v0.0.2
3Protótipobrand, color, UI, UX — three clickable directions, one approved, and docs/product/DESIGN-DIRECTION.md written as the bridge into Phase 4
4DocumentaçãoProduct Brief + Technical Plan reverse-engineered from the prototype, then the roadmap
5ChegadaSprint 0 / Sprint 1

Do not simplify it. Do not skip phases.

Phase 3 runs before Phase 4, deliberately. The prototype is built from BP v0.0.2 and the research; the Product Brief and Technical Plan are then derived from the approved prototype. Never write the Product Brief first and prototype against it — a spec written before the prototype invents completeness the prototype would have shown as gaps.

Do not move to code before all of Phase 1–4 is complete and approved.

Checking your work

npm install                    # once — installs Biome and wires the git pre-commit hook
npm test                       # unit tests for the scripts and hooks
npm run lint                   # Biome: lint + format check (`npm run format` fixes)
node scripts/os-self-test.js   # coherence of the OS itself

Run the ones your change touches before calling it done. A PostToolUse hook already runs Biome on each file you edit and reports back; CI runs all four.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free