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/.
In this repositoryOne other file it gives its agents.
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
- Very specific: line 77
Create rationale/rules/<category>/en/<slug>.md and rationale/rules/<category>/zh/<slug>.md — motivation, context, consequences
- Distinctive: line 78
Add to README.md (and README.zh.md) index table under the right category
- Distinctive: line 79
Add to the Rules to Load table in this CLAUDE.md
- Very specific: line 85
Create rationale/skills/<category>/<subcategory>/<slug>/zh.md — Chinese rationale: trigger scenario, core problem, consequences
- Very specific: line 86
Create rationale/skills/<category>/<subcategory>/<slug>/en.md — English rationale, same structure
- Distinctive: line 87
Add to README.md (and README.zh.md) Skills table under the right category
- Distinctive: line 88
Add to the Skills to Load table in this CLAUDE.md
- Distinctive: line 102
Before/After: if the change is a rewrite or structural change
≈ “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.
Files
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 # MITRules to Load
Code Quality
| Rule | File | Core Requirement |
| Meaningful Comments | rules/code-quality/meaningful-comments.md | Comments MUST explain WHY, not WHAT. Seven types: TODO, references, correctness justification, lessons learned, magic constant rationale, load-bearing details, "why not X" |
| Uncertainty Marking | rules/code-quality/uncertainty-marking.md | Tag uncertain code with [NEEDS VERIFICATION] or [ASSUMPTION: ...]; integrates with Status Honesty via Uncertain field; DONE blocked while tags exist |
| Code Style Declaration | rules/code-quality/code-style-declaration.md | Before ANY code, MUST declare: style baseline, preference decisions (if-else vs strategy, immutability), forbidden patterns |
Workflow
| Rule | File | Core Requirement |
| Commit Messages | rules/workflow/commit-message.md | Commit body MUST answer: what problem forced this change, alternatives considered, trade-offs, surprises |
| Code Review | rules/workflow/code-review.md | Review code not people. Offer actionable suggestions. Ask, don't command. Distinguish blocking from suggestion. Know when to stop |
| Branch & PR Workflow | rules/workflow/branch-pr-workflow.md | Full 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
| Rule | File | Core Requirement |
| Code Change Log | rules/documentation/code-change-log.md | After every Edit/Write, create a change log in docs/变更记录/ with root cause analysis and before/after code |
| README Structure | rules/documentation/readme-structure.md | READMEs MUST follow funnel order: what → why care → how to use → how to install. Show usage before installation |
Communication
| Rule | File | Core Requirement |
| Status Honesty | rules/communication/status-honesty.md | After every code change, report one of four statuses (DONE/PENDING VERIFICATION/BLOCKED/PARTIAL); DONE requires verification checklist |
Skills to Load
Engineering
| Skill | File | Core Capability |
| GitHub PR Workflow | skills/engineering/git-collaboration/github-pr-workflow/SKILL.md | Enterprise Fork + Feature Branch + PR workflow — never commit to main directly |
Conversational
| Skill | File | Core Capability |
| Prompt Composer | skills/conversational/requirement/prompt-composer/SKILL.md | Turn vague requirements into multi-step dialogue scripts — Ask window clarifies, Agent window executes |
| Resume Builder | skills/conversational/interview/resume-builder/SKILL.md | Conversational interview + project code scan to generate role-tailored STAR resume sections |
Atomic
| Skill | File | Core Capability |
| Agent Prompt Engineering | skills/atomic/agent-prompt-engineering/SKILL.md | 5 techniques for writing production Agent prompts: CoT, structured templates, positive/negative examples, divide & conquer, data structure conversion |
Adding a New Rule
- Choose the category (
code-quality|workflow|documentation|communication) and createrules/<category>/<slug>.md— rule description + examples (no rationale in the rule file), with YAML frontmatter (name/title/type/category/summary/translation/applies_to) - Create
rationale/rules/<category>/en/<slug>.mdandrationale/rules/<category>/zh/<slug>.md— motivation, context, consequences - Add to README.md (and README.zh.md) index table under the right category
- Add to the Rules to Load table in this CLAUDE.md
- Re-run
scripts/generate-stats.shand commitstats.json
Adding a New Skill
- 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) - Create
rationale/skills/<category>/<subcategory>/<slug>/zh.md— Chinese rationale: trigger scenario, core problem, consequences - Create
rationale/skills/<category>/<subcategory>/<slug>/en.md— English rationale, same structure - Add to README.md (and README.zh.md) Skills table under the right category
- Add to the Skills to Load table in this CLAUDE.md
- Re-run
scripts/generate-stats.shand commitstats.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.
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
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.

