agentleFS
SiborneSiborne/vibe-coding-sops/CLAUDE.md

vibe-coding-sops

CLAUDE.md2 starsChanged 3 months agoMITView on GitHub

vibe-coding-sops stores rules for AI-assisted coding (vibe coding). Each rule defines what to do and how (rules/), paired with a rationale explaining why (rationale/). When this repo is loaded into your project's context, you must follow all rules in rules/.

The file

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

8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Create rationale/rules/<category>/en/<slug>.md and rationale/rules/<category>/zh/<slug>.md — motivation, context, consequences

    line 77
  2. Distinctive:

    Add to README.md (and README.zh.md) index table under the right category

    line 78
  3. Distinctive:

    Add to the Rules to Load table in this CLAUDE.md

    line 79
  4. Very specific:

    Create rationale/skills/<category>/<subcategory>/<slug>/zh.md — Chinese rationale: trigger scenario, core problem, consequences

    line 85
  5. Very specific:

    Create rationale/skills/<category>/<subcategory>/<slug>/en.md — English rationale, same structure

    line 86
  6. Distinctive:

    Add to README.md (and README.zh.md) Skills table under the right category

    line 87
  7. Distinctive:

    Add to the Skills to Load table in this CLAUDE.md

    line 88
  8. Distinctive:

    Before/After: if the change is a rewrite or structural change

    line 102

≈ “Common” is an estimate: at least 1 in 5 of the 27,641 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

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

vibe-coding-sops stores rules for AI-assisted coding (vibe coding). Each rule defines what to do and how (rules/), paired with a rationale explaining why (rationale/).

When this repo is loaded into your project's context, you must follow all rules in rules/.

Repository Structure

rules/               # Rule files — what to do, how to do it, grouped into 4 categories
  code-quality/      #   meaningful-comments, uncertainty-marking, code-style-declaration
  workflow/          #   commit-message, code-review, branch-pr-workflow
  documentation/     #   code-change-log, readme-structure
  communication/     #   status-honesty
rationale/rules/     # Rule rationale — mirrors rules/: <category>/<en|zh>/<name>.md
rationale/skills/    # Skill rationale — mirrors skills/: <category>/<subcategory>/<name>/<en|zh>.md
skills/              # Reusable AI skills, grouped into 3 categories
  engineering/       #   fixed-process skills
  conversational/    #   dialogue-driven skills
  atomic/            #   single-purpose technique units
README.md            # Rule & skill index with badges and quick-start guide
LICENSE              # MIT

Rules to Load

Code Quality

RuleFileCore Requirement
Meaningful Commentsrules/code-quality/meaningful-comments.mdComments MUST explain WHY, not WHAT. Seven types: TODO, references, correctness justification, lessons learned, magic constant rationale, load-bearing details, "why not X"
Uncertainty Markingrules/code-quality/uncertainty-marking.mdTag uncertain code with [NEEDS VERIFICATION] or [ASSUMPTION: ...]; integrates with Status Honesty via Uncertain field; DONE blocked while tags exist
Code Style Declarationrules/code-quality/code-style-declaration.mdBefore ANY code, MUST declare: style baseline, preference decisions (if-else vs strategy, immutability), forbidden patterns

Workflow

RuleFileCore Requirement
Commit Messagesrules/workflow/commit-message.mdCommit body MUST answer: what problem forced this change, alternatives considered, trade-offs, surprises
Code Reviewrules/workflow/code-review.mdReview code not people. Offer actionable suggestions. Ask, don't command. Distinguish blocking from suggestion. Know when to stop
Branch & PR Workflowrules/workflow/branch-pr-workflow.mdFull lifecycle: branch naming (feat/fix/refactor/docs/chore/test), PR scope (semantic completeness), rebase-first sync, 3-layer pre-merge checklist, reviewer merge + cleanup

Documentation

RuleFileCore Requirement
Code Change Logrules/documentation/code-change-log.mdAfter every Edit/Write, create a change log in docs/变更记录/ with root cause analysis and before/after code
README Structurerules/documentation/readme-structure.mdREADMEs MUST follow funnel order: what → why care → how to use → how to install. Show usage before installation

Communication

RuleFileCore Requirement
Status Honestyrules/communication/status-honesty.mdAfter every code change, report one of four statuses (DONE/PENDING VERIFICATION/BLOCKED/PARTIAL); DONE requires verification checklist

Skills to Load

Engineering

SkillFileCore Capability
GitHub PR Workflowskills/engineering/git-collaboration/github-pr-workflow/SKILL.mdEnterprise Fork + Feature Branch + PR workflow — never commit to main directly

Conversational

SkillFileCore Capability
Prompt Composerskills/conversational/requirement/prompt-composer/SKILL.mdTurn vague requirements into multi-step dialogue scripts — Ask window clarifies, Agent window executes
Resume Builderskills/conversational/interview/resume-builder/SKILL.mdConversational interview + project code scan to generate role-tailored STAR resume sections

Atomic

SkillFileCore Capability
Agent Prompt Engineeringskills/atomic/agent-prompt-engineering/SKILL.md5 techniques for writing production Agent prompts: CoT, structured templates, positive/negative examples, divide & conquer, data structure conversion

Adding a New Rule

  1. Choose the category (code-quality | workflow | documentation | communication) and create rules/<category>/<slug>.md — rule description + examples (no rationale in the rule file), with YAML frontmatter (name/title/type/category/summary/translation/applies_to)
  2. Create rationale/rules/<category>/en/<slug>.md and rationale/rules/<category>/zh/<slug>.md — motivation, context, consequences
  3. Add to README.md (and README.zh.md) index table under the right category
  4. Add to the Rules to Load table in this CLAUDE.md
  5. Re-run scripts/generate-stats.sh and commit stats.json

Adding a New Skill

  1. Choose the category + subcategory (engineering: git-collaboration · code-quality · testing · delivery; conversational: requirement · interview · brainstorm; atomic: none) and create skills/<category>/<subcategory>/<slug>/SKILL.md — skill definition with techniques, examples, and selection guide, with YAML frontmatter (name/title/description/type/category/subcategory/triggers/tags)
  2. Create rationale/skills/<category>/<subcategory>/<slug>/zh.md — Chinese rationale: trigger scenario, core problem, consequences
  3. Create rationale/skills/<category>/<subcategory>/<slug>/en.md — English rationale, same structure
  4. Add to README.md (and README.zh.md) Skills table under the right category
  5. Add to the Skills to Load table in this CLAUDE.md
  6. Re-run scripts/generate-stats.sh and commit stats.json

Self-Application: This Repo's Own Change Log

This repo's rules apply to Claude Code when editing THIS repo. Specifically:

Every time you modify files in this repo, create a change log in docs/变更记录/.

Naming: <brief-description>_<YYYY-MM-DD>.md

The change log must include:

  • What was changed (files, sections)
  • Why the change was made (user request, rule clarification, fix)
  • Before/After if the change is a rewrite or structural change

This ensures the evolution of the rules themselves is traceable — the meta-rule applies to its own home.

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.