jacartyjacarty/claude-toolkit/CLAUDE.md

claude-toolkit

CLAUDE.md0 starsChanged 6 months agoMITView on GitHub

PRD: docs/prd/v1.0-prd.md Build Guide: docs/build-guides/v1.0-build-guide.md Process: docs/process.md — branch/PR cadence, pre-commit + pre-PR agent gates, trivial-change fast path, phase-boundary rituals. Read this before any feature work. These are non-negotiable. They apply to every session regardless of scope. - How auth tokens flow through the system - How errors are structured and propagated - Shared module/helper contracts - Naming conventions for files, functions, routes - Data model patterns (e.g. DynamoDB single-table design, SQL schema conventions) --> Branch strategy: Feature branches →…

In this repository9 other files it gives its agents.
- design-thinking-ideationSkill
- graph-of-thoughtSkill
- implementation-specSkill
- requirements-elicitationSkill
- research-briefSkill
- trade-off-analysisSkill
- tree-of-thoughtSkill
- value-chain-analysisSkill
- vrio-analysisSkill

The file

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

11 rules. About 0 are common, 9 are distinctive, and 2 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈9
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
could be automatic: a setting could enforce it

Distinctive:
Never commit directly to main: Always create a feature or fix branch and open a PR.
line 21
Distinctive:
Before pushing, verify only intended files are staged: Run git status and git diff --cached --name-only before every commit.
line 22
Very specific:
Run lint + tests + build locally before opening a PR: Do not rely on CI to catch issues.
line 23
Distinctive:
Do not introduce [library X] — this codebase uses [library Y] for that purpose.
line 27
Distinctive:
Always use MCP servers (Linear, GitHub) over manual API calls when available.
line 29
Distinctive:
When the build guide or user specifies TDD:
line 33
Distinctive:
Write a failing test that captures the acceptance criteria
line 34
Distinctive:
Run the full test suite and iterate until green
line 36
Distinctive:
Do not skip step 1. The test is the specification.
line 38
Distinctive:
Keep this updated — the doc-generator agent refreshes it at phase boundaries.
line 84
Very specific:
Run tests: npm test / pytest / etc.
line 111

≈ “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

[Project Name] — Claude Code Context

Project Overview

PRD: docs/prd/v1.0-prd.md Build Guide: docs/build-guides/v1.0-build-guide.md Process: docs/process.md — branch/PR cadence, pre-commit + pre-PR agent gates, trivial-change fast path, phase-boundary rituals. Read this before any feature work.

<!-- If using issue tracking, add details here:
**Issue Tracking:** [Tool] — [project/board name], [team/key]
-->

Rules

These are non-negotiable. They apply to every session regardless of scope.

Never commit directly to main. Always create a feature or fix branch and open a PR. No exceptions.
Before pushing, verify only intended files are staged. Run git status and git diff --cached --name-only before every commit. Do not include unrelated config files, lockfile churn, or editor artefacts.
Run lint + tests + build locally before opening a PR. Do not rely on CI to catch issues. The pre-PR gates in docs/process.md exist to shift catches earlier, not replace local validation.
Read docs/process.md before any feature work. It defines the agent cadence, trivial-change fast path, and fold timing. Follow it.

<!-- Add project-specific rules below as you discover them. Examples:
- Do not introduce [library X] — this codebase uses [library Y] for that purpose.
- Terraform must apply before Amplify builds when env vars change.
- Always use MCP servers (Linear, GitHub) over manual API calls when available.
-->

<!-- TDD mode (activate per-project):
When the build guide or user specifies TDD:
1. Write a failing test that captures the acceptance criteria
2. Implement minimum code to make it pass
3. Run the full test suite and iterate until green
4. Proceed to the next requirement
Do not skip step 1. The test is the specification. -->

[Frontend]
    → [API Layer]
    → [Compute]
    → [Data Store]

Frontend:
Auth:
API:
Compute:
Persistence:
IaC:
CI/CD:

<!-- Example:
**Cloud Account:** 123456789012
**Region:** eu-west-1
**GitHub Repo:** user/repo
-->

Repository Structure

project/
├── CLAUDE.md                        # This file
├── docs/
│   ├── prd/                         # Product requirements
│   ├── build-guides/                # Implementation guides
│   ├── process.md                   # Development process and agent cadence
│   ├── tech-debt.md                 # Known gaps and drift
│   └── decisions/                   # Architecture Decision Records
├── ...                              # Project-specific structure

<!-- Document your project's directory structure here.
     Keep this updated — the doc-generator agent refreshes it at phase boundaries. -->

Key Patterns

<!-- Document the important architectural patterns, conventions, and contracts
     that someone working on the codebase needs to know. Examples:

- How auth tokens flow through the system
- How errors are structured and propagated
- Shared module/helper contracts
- Naming conventions for files, functions, routes
- Data model patterns (e.g. DynamoDB single-table design, SQL schema conventions)
-->

Testing

Level	Tool	Scope
Unit
Integration
E2E

<!-- Add run commands:
Run tests: `npm test` / `pytest` / etc.
-->

Git Workflow

Branch strategy: Feature branches → PR → merge to main.

main                    ← production; protected
└── feature/<slug>      ← feature work
└── fix/<slug>          ← bug fixes

Deployment

<!-- How does code get from main to production?
- Infrastructure: terraform apply / CloudFormation / etc.
- Application: auto-deploy on merge / manual deploy / etc.
- CI/CD: which workflows run on PR vs merge
-->

Common Pitfalls & Constraints

<!-- Document the things that have bitten you or will bite someone new.
     These are the hard-won lessons — keep them updated.

Examples:
- Service X has a 30s timeout that affects Y
- Config Z must be set before first deploy
- Region constraint on service W
- Item size limits on data store
-->

Updating this document

This file is maintained by the doc-generator agent at phase boundaries and should reflect the current state of the codebase. If you notice drift between this document and reality, fix it — stale context is worse than no context.

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