What Is CLAUDE.md in the AI-Berkshire Repository? A Complete Guide

CLAUDE.md is the canonical project-level instruction document that defines the structure, workflow, and coding standards for the AI-Berkshire investment research platform when used with Claude Code.

The AI-Berkshire repository by xbtlin is an open-source collection of AI-driven investment research Skills built on Claude Code. This specialized markdown file serves as the primary configuration guide for contributors and the Claude Code AI assistant, establishing everything from directory organization to mandatory financial verification procedures.

What Is CLAUDE.md?

In the context of the AI-Berkshire repository, CLAUDE.md functions as the central instruction manual for Claude Code users. Located at the repository root, this file specifies how the codebase is organized, how research reports should be written and named, and what analytical standards must be followed when executing the investment research Skills.

Unlike a generic README, CLAUDE.md is specifically optimized for AI assistant consumption. It provides the contextual foundation that allows Claude Code to understand the project's purpose—modeling investment decision-making frameworks from four "masters" (巴菲特, 芒格, 段永平, and 李录)—and generate consistent, high-quality research outputs accordingly.

Key Sections of CLAUDE.md

The document is organized into several critical sections that govern repository usage.

Project Overview and Purpose

The 项目概述 section establishes that AI-Berkshire is a suite of investment-research Skills built on Claude Code. It covers four distinct investment philosophies derived from prominent value investors, ensuring that all generated analysis adheres to these specific frameworks.

Repository Structure

The 项目结构 section maps the top-level directories:

• skills/ — Contains markdown Skill definitions that Claude Code executes
• tools/ — Houses helper scripts including financial_rigor.py
• reports/ — Stores generated research reports organized by company or industry
• assets/ — Holds static images and supporting media

Report Organization and Naming Conventions

The 报告目录结构 & 命名规范 section enforces strict organizational standards. Reports must be organized by company or industry within the reports/ directory, following specific naming conventions for each Skill type (e.g., /investment-research, /earnings-review).

Core Analytical Principles

The 核心原则 section mandates objective, data-driven analysis with strict separation of facts versus opinions. It requires multi-source verification for all financial claims, ensuring research integrity across all AI-generated outputs.

GitHub Workflow and Commands

The GitHub 操作 & 常用命令 section provides the recommended clone path (~/ai-berkshire), remote URL configuration, and standardized Git workflows for adding new reports.

Mandatory Quality Checks

CLAUDE.md enforces specific validation procedures through its 注意事项 section. Contributors must verify market-cap calculations, ensure unit consistency across financial statements, and validate all financial metrics using tools/financial_rigor.py before submitting reports.

Practical Usage Examples

The following workflows demonstrate how CLAUDE.md directives translate into daily repository operations.

Creating a New Investment Research Report

Following the naming conventions specified in CLAUDE.md, create research files using the company name and date format:

# Clone the repository to the prescribed path

git clone https://github.com/xbtlin/ai-berkshire.git ~/ai-berkshire
cd ~/ai-berkshire

# Create the report directory and file following the naming convention

mkdir -p reports/腾讯
touch reports/腾讯/腾讯-research-20260408.md

# Edit the file according to the Skill specifications

vim reports/腾讯/腾讯-research-20260408.md

Running Financial Validation

As required by the mandatory checks section, validate financial metrics before submission:

# Calculate PE, ROE, and other precise metrics

python3 tools/financial_rigor.py --ticker TCEHY --date 2026-04-08

Standard Git Workflow for Contributions

The document specifies a rebase-oriented workflow to maintain clean history:

# Stage the new research report

git add reports/腾讯/腾讯-research-20260408.md

# Commit with descriptive Chinese message format

git commit -m "添加腾讯 2026‑04‑08 研究报告"

# Sync with remote using rebase strategy

git pull --rebase origin main
git push origin main

Synchronizing Skills After Modifications

When updating Skill definitions in skills/, regenerate the associated artifacts:

# Re-generate Codex artifacts after editing skills

python3 scripts/sync-codex-skills.py

Relationship to AGENTS.md

While CLAUDE.md serves as the Claude Code-specific instruction set, the repository also contains AGENTS.md, which provides a high-level overview compatible with multiple AI assistants including Codex. CLAUDE.md contains the granular, workflow-specific instructions that Claude Code requires to execute the investment research Skills effectively, whereas AGENTS.md offers broader architectural context.

Summary

• CLAUDE.md is the canonical instruction document that governs how Claude Code interacts with the AI-Berkshire repository.
• It defines the project structure, specifying the roles of skills/, tools/, reports/, and assets/ directories.
• The file enforces strict naming conventions for research outputs organized by company or industry.
• Core principles mandate objective, data-driven analysis with clear separation between facts and opinions.
• Mandatory validation requires using tools/financial_rigor.py for all financial metric calculations.
• The document specifies Git workflows including specific clone paths and rebase-based synchronization.

Frequently Asked Questions

What is the difference between CLAUDE.md and a regular README?

CLAUDE.md is specifically optimized for AI assistant consumption rather than human readers. While a traditional README provides general project information, CLAUDE.md contains machine-readable instructions about project structure, specific naming conventions, and workflow commands that allow Claude Code to generate consistent investment research outputs according to the AI-Berkshire methodology.

Why does CLAUDE.md specify exact directory paths like ~/ai-berkshire?

The specified clone path ensures that Claude Code can reliably locate tools and scripts regardless of the user's environment. By standardizing on ~/ai-berkshire, the document ensures that relative paths in helper scripts like tools/financial_rigor.py and automation workflows function correctly across different contributor setups.

Do I need to run financial_rigor.py before every commit?

Yes, according to the 注意事项 section in CLAUDE.md, running python3 tools/financial_rigor.py is mandatory for verifying market-cap calculations, ensuring unit consistency, and validating financial metrics. This requirement ensures that all research reports in the reports/ directory maintain the data integrity standards required by the four investment masters' frameworks.

Can I use CLAUDE.md with other AI coding assistants besides Claude Code?

While CLAUDE.md is specifically designed for Claude Code, the repository includes AGENTS.md which provides compatible instructions for other AI assistants like Codex. However, the granular workflow specifications, Skill execution patterns, and directory conventions detailed in CLAUDE.md are optimized specifically for Claude Code's architecture and may not translate perfectly to other AI assistant platforms.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}