Skip to content

Instantly share code, notes, and snippets.

@rjurney

rjurney/CLAUDE.md

Created June 16, 2025 15:03
Show Gist options
  • Save rjurney/3f8258de133658afed6fac05b0d20bef to your computer and use it in GitHub Desktop.
Save rjurney/3f8258de133658afed6fac05b0d20bef to your computer and use it in GitHub Desktop.
Download ZIP
Example of a `CLAUDE.md` file to tune Claude Code's performance. Refer to it to create your own `CLAUDE.md`
Raw
CLAUDE.md

CLAUDE.md

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

Commands

  • Install Dependencies: poetry install
  • Run CLI: poetry run abzu
  • Build/Generate abzu/baml_client code: baml-cli generate
  • Test baml_src code: baml-cli test, poetry run pytest tests/
  • Test single: poetry run pytest tests/path_to_test.py::test_name
  • Lint: pre-commit run --all-files, poetry run flake8
  • Format: poetry run black ., poetry run isort .
  • Type check: poetry run mypy

Code Style

  • Line length: 100 characters
  • Python version: 3.12
  • Formatter: black with isort (profile=black)
  • Types: Always use type annotations, warn on any return
  • Imports: Use absolute imports, organize imports to be PEP compliant with isort (profile=black)
  • Error handling: Use specific exception types with logging
  • Naming: snake_case for variables/functions, CamelCase for classes
  • BAML: Use for LLM-related code, regenerate client with baml-cli generate
  • Whitespaces: leave no trailing whitespaces, use 4 spaces for indentation, leave no whitespace on blank lines
  • Strings: Use double quotes for strings, use f-strings for string interpolation
  • Docstrings: Use Numpy style for docstrings, include type hints in docstrings
  • Comments: Use comments to explain complex code, avoid obvious comments
  • Tests: Use pytest for testing, include type hints in test functions, use fixtures for setup/teardown
  • Tests: Don't make a class to contain unit tests. Just write the tests in pytest style.
  • Type hints: Use Python 3.9 type hints for all function parameters and return types. Use list, dict, tuple, etc. instead of List, Dict, Tuple from the typing module. Use Optional from the typing module for optional parameters.
  • Type checking: Use mypy for type checking, run mypy before committing code
  • Logging: Use logging for error handling, avoid print statements
  • Documentation: Use Sphinx for documentation, include docstrings in all public functions/classes
  • Code style: Follow PEP 8 for Python code style, use flake8 for linting
  • Mypy: Use mypy for type checking, run mypy before committing code. Configure it in pyproject.toml, not mypy.ini.
  • Pre-commit: Use pre-commit for linting and formatting, configure it in .pre-commit-config.yaml
  • Git: Use git for version control, commit often with clear messages, use branches for new features/bug fixes. Always test new features in the CLI before you commit them.
  • Poetry: Use poetry for dependency management and packaging, configure it in pyproject.toml
  • discord.py package - always use selective imports for discord - YES from discord import x - NO import discord
  • Use abzu.config.Config - use the Config class from abzu.config which has an instance abzu.config.config to access configuration values. Do not hardcode configuration values in the codebase. If you need to add a new configuration value, add it to the config.yml file and access it through the Config class's instance via from abzu.config import config and config.get(key).
  • External strings - we store all strings in config.yml and use the abzu.config.config instance to access them. Do not hardcode strings in the codebase. If you need to add a new string, add it to the config.yml file and access it through the Config class's instance via from abzu.config import config and config.get(key).
  • Imports - always import up top in PEP8 format. Do not import inside functions or classes. Use absolute imports, not relative imports. Do not use wildcard imports (e.g., from module import *). Always import specific classes or functions from modules.
  • Submodules - submodules go under subs/. Ignore them completely. Never write to submodules in anything you do.
  • Space Lines - never create a line with only spaces.
  • Imports - don't check if things are installed and handle it with a try/except. Instead, assume they are installed and import them directly. If they are not installed, the code will fail at runtime, which is acceptable in this project.
  • Always put spaces around operators and variables, e.g. x = 1 + 2, not x=1+2

Claude Logic

  • Find the root cause of an issue before figuring out a solution. Fix problems.
  • Do not create workarounds for issues without asking. Always find the root cause of an issue and fix it.
  • Command Line Interfaces - at the end of your coding tasks, please alter the 'abzu' CLI to accommodate the changes.
  • Separate logic from the CLI - separate the logic under abzu and sub-modules from the command line interface (CLI) code in abzu.cli. The CLI should only handle input/output from/to the user and should not contain any business logic. For example the module for abzu process kg should be in abzu.kg.* and not in abzu.cli.api. Similarly, the module for abzu process articles should be in abzu.articles.* and not in abzu.cli.api.
  • Read the README - consult the README before taking action. The README contains information about the project and how to use it. If you need to add a new command or change an existing one, consult the README first.
  • Update the README - if appropriate, update the README with any new commands or changes to existing commands. The README should always reflect the current state of the project.
  • Use Poetry - use poetry for dependency management and packaging. Do not use pip or conda.
  • Use BAML - use BAML for LLM-related code. Do not use any other libraries or frameworks for LLM-related code. BAML is an extension of Jinja2 and is used for templating LLM information extraction in this project. Use BAML to generate code for the BAML client and to process data.
  • DO NOT WRITE TO the abzu.baml_client directory. This directory is generated by the baml-cli generate command and should not be modified directly. Instead, use the baml-cli generate command to regenerate the client when needed.
  • Use PySpark for ETL - use PySpark for ETL and batch data processing to build our knowledge graph. Do not use any other libraries or frameworks for data processing. Use PySpark to take the output of our BAML client and transform it into a knowledge graph.
  • PySpark - Do not break up dataflow into functions for loading, computing this, computing that, etc. Create a single function that performs the entire dataflow at hand. Do not check if columns exist, assume they do. Do not check if paths exist, assume they do. We prefer a more linear flow for Spark scripts and simple code over complexity. This only applies to Spark code.
  • Flake8 - fix flake8 errors without being asked and without my verification.
  • Black - fix black errors without being asked and without my verification.
  • Isort - fix isort errors without being asked and without my verification.
  • Mypy - fix mypy errors without being asked and without my verification.
  • Pre-commit - fix pre-commit errors without being asked and without my verification.
  • New Modules - create a folder for a new module without being asked and without my verification.
  • init.py - add these files to new module directories without being asked and without my verification.
  • Edit Multiple Files at Once - if you need to edit multiple files for a single TODO operation, do so in a single step. Do not create multiple steps for the same task.
  • abzu steps Command - Add new steps in the data pipeline to the abzu steps command. This command is used to run the data pipeline in a specific order. The steps should be added in the order they are executed in the pipeline. If you aren't sure about the order, ask me.
  • Git - Keep commit messsages straightforward and to the point - do not put extraneous details, simply summarize the work performed. Do not put anything in commit messages other than a description of the code changes. Do not put "Generated with Claude Code" or anything else relating to Claude or Anthropic.
  • Git Log - use the git log command to view the commit history to understand the context or recent changes to the codebase. This will help you understand the project better and make informed decisions when writing code.
  • Do not use 'rm' to remove files - use git rm to remove files from the repository. This will ensure that the files are removed from the git history as well.
  • I repeat, NEVER TALK ABOUT YOURSELF IN COMMIT MESSAGES. Do not put "Generated with Claude Code" or anything else relating to Claude or Anthropic in commit messages. Commit messages should only describe the code changes made, not the tool used to make them.
  • Ask questions before mitigating a simple problem with a complex fix.

Alerts

  • BEEP only ONCE when you are done with something and prompt me, the user in your UI. I need to hear that you're done because I do more than one thing at once. Use the command echo -ne '\007' to beep. Do not keep beeping multiple times or continuously. Just beep once when you are done with a task.
  • Use the applescript-mcp server to send me a message when you are done with something. Say "Done with task X" where X is the task you are done with. Alternatively, use the command osascript -e 'tell application "System Events" to display dialog "Done with task X"' to send me a message. Send only ONE alert, not multiple alerts.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment