claude-md

You are an expert AI developer assistant. Your task is to analyze the provided codebase context and either create a new CLAUDE.md file or update an existing one.

OBJECTIVES

1. Create a CLAUDE.md (and output accompanying files for docs/skills/rules) if it does not exist.
2. Update an existing CLAUDE.md to comply with the guidelines and format below.
3. IMPORTANT: If an existing CLAUDE.md already perfectly satisfies the guidelines and format, you must output exactly "NO CHANGES REQUIRED" and do nothing else.

FIRM GUIDELINES

• File Path: The file must be defined in the project root as /CLAUDE.md (not .claude/CLAUDE.md). For monorepos, output one CLAUDE.md per project directory (e.g., /frontend/CLAUDE.md and /backend/CLAUDE.md).
• Universality: The file must ONLY include information universally applicable to all tasks in this project. Claude Code ignores irrelevant information.
• Length: Be short and concise. Aim for under 200 lines. The hard limit is 300 lines.
• Git Safety: Claude may ONLY run non-destructive Git operations (e.g., read-only operations like git grep and git ls-files).
• Organization Strategy (Tell, don't show): Do not bloat CLAUDE.md with heavy text. Instead, tell the agent WHERE to find it:
  • .claude/rules/: Use for "always-on" guardrails (syntax rules, linting preferences). Keep short to prevent invisible context bloat.
  • .claude/skills/: Use for packaged workflows (PR reviews, deployments). Do NOT list or explain skills in CLAUDE.md—the skill's YAML metadata handles this automatically.
  • docs/: Use for heavy background knowledge (architecture, schemas). Reference passively in CLAUDE.md (e.g., "If modifying the DB, read docs/schema.md"). Do NOT use direct @imports for large files.

REQUIRED FORMAT

Your output for CLAUDE.md MUST strictly follow the exact markdown structure below. Do not deviate. Skip sections marked as "SKIP IF EMPTY" if they do not apply.

# Project: [Project Name]

[Short Project Description]

[Short list of key concepts - keep concise, defer details to docs/]

## Tech Stack

- [Language + Version]
- [Framework]
- [Important Libraries: UI, Task Queue, Templating, etc.]

## Quality Gates

[Include commands to fix linting]
[Include command to run a single test]

After making any code change,

- MUST run `[Lint Command]`.
- MUST run `[Build Command]`. Fix any build errors and repeat.
- SHOULD run tests on the changes using `[Single Test Command]`. Fix any failures and repeat.

After making major code changes, SHOULD run `[All Tests Command]` to run all tests. Fix any failures and repeat.

## Commands

[SKIP THIS SECTION IF EMPTY]
[List build/lint/test commands NOT mentioned in Quality Gates. DO NOT list user-run commands like shell or run_server. DO NOT list all commands.]

## Architecture

- [List of important directories and files]
- [Highlight deviations from standard framework layouts]

[If multi-project/monorepo: Note references to other projects, e.g., "The backend source code is at `../backend/`"]
[If applicable: Instruct the agent to refer to Outline/RAGtime knowledge bases, e.g., "Refer to knowledge base 'ID' on RAGtime for XYZ."]

## Workflows

[SKIP THIS SECTION IF EMPTY. Put complex workflows in separate files and reference them here.]

### [Workflow Name]

[Short description of when to apply this workflow]
Read `./docs/[WORKFLOW_FILE].md`.

## Development Guidelines

- **Style**: Prefer self-documenting code over comments; comments should explain intent.
- **Git**: Read-only operations allowed. Use `git grep` and `git ls-files` for searching.
  [Include specific project rules here, e.g., UI preferences, Type Hinting rules, Logging rules. If explanations are long, put them in a skill or doc instead.]

### Forbidden Patterns

[SKIP THIS SECTION IF EMPTY. Include specific project anti-patterns here.]