YouTip

A typical Claude Code project directory structure is as follows:

your-project/
├── CLAUDE.md              ← Team shared instructions, committed to git
├── CLAUDE.local.md        ← Personal overrides, git ignored
└── .claude/
    ├── settings.json          ← Permissions + config, committed to git
    ├── settings.local.json    ← Personal permissions, git ignored
    ├── commands/              ← Custom slash commands
    │   ├── review.md        → /project:review
    │   ├── fix-issue.md     → /project:fix-issue
    │   └── deploy.md        → /project:deploy
    ├── rules/                 ← Modular instruction files (globally effective)
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/                ← Auto-invoked workflows
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    └── agents/                ← Sub-agent role definitions
        ├── code-reviewer.md
        └── security-auditor.md

---

CLAUDE.md -- Project Core Instructions

CLAUDE.md

This is the first file Claude reads when entering the project, equivalent to a project welcome manual.

CLAUDE.md is placed in the project root directory and shared by all team members. It tells Claude: what this project is, how to run it, and what conventions it follows.

Typical content:

# My Project

One sentence describing the project purpose.

## Tech Stack
- Backend: Python / FastAPI
- Frontend: React + TypeScript
- Database: PostgreSQL

## Common Commands
`npm run dev`      # Start development server
`pytest tests/`    # Run tests
`npm run build`    # Build production version

## Code Conventions
- Use snake_case for variable naming
- All APIs need unit tests
- PRs must pass CI before merging

## Architecture Overview
src/
├── api/       # FastAPI routing layer
├── services/  # Business logic layer
└── models/    # Data model layer

💡 Tip: Claude will automatically recursively read CLAUDE.md in parent directories. In a monorepo, a sub-package can contain another CLAUDE.md, and Claude will merge and understand both layers of instructions.

CLAUDE.local.md

A personal override layer, applied on top of CLAUDE.md.

CLAUDE.local.md stores preferences or temporary instructions relevant only to you, which should not be shared with the team.

Typical content:

# My Local Overrides
Local database address: localhost:5433 (non-default port)
Please output detailed logs first when debugging.

## Temporary Rules (for this task)
Currently focused on refactoring the auth/ module, do not modify other modules for now.

---

.claude/settings.json -- Permissions and Configuration Center

settings.json

Team shared configuration file that controls which actions Claude is allowed or forbidden to perform, serving as the team security baseline.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(pytest:*)",
      "Bash(git diff:*)",
      "Bash(git log:*)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl * | bash)"
    ]
  }
}

settings.local.json

Personal local permission overrides, temporarily relaxing or tightening certain permissions without affecting other team members.

{
  "permissions": {
    "allow": [
      "Bash(rm ./tmp/*)"
    ]
  }
}

---

.claude/commands/ -- Custom Slash Commands

Each .md file in this directory is automatically mapped to a /project:filename command.

.claude/commands/ is the core mechanism for teams to standardize repetitive tasks.

Filename	Corresponding Command
review.md	/project:review
fix-issue.md	/project:fix-issue
deploy.md	/project:deploy

Example: commands/review.md

# Code Review

Please perform a complete code review of the current changes:

1. Check for security vulnerabilities (SQL injection, XSS, etc.)
2. Verify error handling is complete
3. Confirm test coverage meets standards
4. Check compliance with code style conventions
5. Evaluate performance impact

Output a structured review report in Chinese, sorted by severity.

Example: commands/fix-issue.md (with parameters)

# Fix GitHub Issue

Given Issue number $ARGUMENTS, please:

1. Read and understand the Issue description
2. Locate relevant code files
3. Implement a minimal fix
4. Write corresponding unit tests
5. Update CHANGELOG.md

Invocation: /project:fix-issue 123

💡 Parameter Passing: Command files can use the $ARGUMENTS placeholder to receive parameters passed at invocation time.

---

.claude/rules/ -- Modular Behavior Rules

Split rules from CLAUDE.md into modular files, which Claude follows throughout the entire session. Suitable for long-term stable behavioral conventions, preventing CLAUDE.md from becoming too bloated.

Example: rules/code-style.md

# Code Style Rules

- TypeScript strict mode, disable any type
- Function length not exceeding 40 lines, split if exceeded
- Prefer const, avoid let
- Import order: standard library → third-party packages → local modules
- All exported functions/types need JSDoc comments
- Prohibit console.log, use project logger

Example: rules/testing.md

# Code Style Rules

- TypeScript strict mode, disable any type
- Function length not exceeding 40 lines, split if exceeded
- Prefer const, avoid let
- Import order: standard library → third-party packages → local modules
- All exported functions/types need JSDoc comments
- Prohibit console.log, use project logger

Example: rules/api-conventions.md

# API Conventions

- RESTful style, resource names in plural form
- Unified response format: { data, error, meta }
- Error codes follow HTTP standard semantics
- All endpoints need to be declared in OpenAPI documentation
- Pagination parameters uniformly use page / page_size

---

.claude/skills/ -- Auto-invoked Workflows

Skills are more advanced composite workflows. When Claude determines that a task is suitable for a particular skill, it will automatically read and execute the corresponding SKILL.md, without manual invocation.

Each skill is a subdirectory containing SKILL.md.

Example: skills/security-review/SKILL.md

# Security Review Skill

## Trigger Conditions
Automatically triggered when user requests code review, or code involves authentication/authorization/encryption/user input handling.

## Execution Steps
1. Scan for SQL injection risks (check all database queries)
2. Check XSS protection (verify output escaping)
3. Audit permission boundaries (confirm least privilege principle)
4. Check sensitive data handling (whether leaked in logs, error messages)
5. Output OWASP Top 10 comparison checklist

## Output Format
Sorted by CVSS score, high-severity issues displayed first.

⚡ Skills vs Commands Difference:

• Commands require user to actively input slash commands to trigger, they are a "toolbox"
• Skills are automatically invoked by Claude based on context, they are "intelligent instincts"

---

.claude/agents/ -- Sub-agent Roles

Define specialized sub-agents that can be dispatched by the main Claude instance. In complex tasks, the main agent delegates subtasks to corresponding expert roles, achieving multi-agent collaboration. Sub-agents run in isolated contexts with independent permission scopes.

Example: agents/code-reviewer.md

---
name: code-reviewer
description: Senior code reviewer, focused on code quality and maintainability
---

# Code Reviewer

## Role Positioning
You are a senior engineer with 10 years of experience, focused on code readability, performance optimization, and best practices.

## Review Focus
- Whether naming clearly expresses intent
- Single responsibility principle for functions/classes
- Boundary conditions and error handling
- Performance bottlenecks (N+1 queries, unnecessary loops, etc.)

## Permissions
Read-only access, do not directly modify files.

## Output Format
Use Markdown table output, containing: issue location, severity, suggested solution.

Example: agents/security-auditor.md

---
name: security-auditor
description: Security audit expert, focused on vulnerability scanning and compliance auditing
---

# Security Auditor

## Role Positioning
You are a security engineer, familiar with OWASP, CVE database, and common attack vectors.

## Audit Scope
- Authentication and authorization logic
- Input validation and output escaping
- Known vulnerabilities in dependency packages (combined with npm audit / pip audit)
- Sensitive information leakage risks

## Permissions
Read-only access + can run security scanning tools.

## Output Format
Sorted by CVSS 3.1 score, containing: vulnerability description, impact scope, remediation suggestion, reference links.

---

Quick Reference Table

File / Directory	Commit to Git	Trigger Method	Core Purpose
CLAUDE.md	✅ Yes	Automatic (at startup)	Project base instructions and conventions
CLAUDE.local.md	❌ No	Automatic (at startup)	Personal overrides, temporary instructions
.claude/settings.json	✅ Yes	Automatic (at startup)	Team permission baseline
.claude/settings.local.json	❌ No	Automatic (at startup)	Personal permission overrides
.claude/commands/*.md	✅ Yes	Manual (/project:xxx)	Reusable standardized processes
.claude/rules/*.md	✅ Yes	Automatic (globally effective)	Modular behavior conventions
.claude/skills/*/SKILL.md	✅ Yes	Automatic (Claude judges)	Intelligent composite workflows
.claude/agents/*.md	✅ Yes	Automatic (main agent dispatches)	Professional sub-agent role definitions

---

Best Practice Recommendations

Start from minimum viable configuration:

your-project/
├── CLAUDE.md              # Start here
└── .claude/
    └── settings.json      # Configure basic permissions

As the project evolves, gradually introduce:

1. commands/ — When you find yourself repeatedly inputting the same instructions
2. rules/ — When CLAUDE.md exceeds 100 lines, split into modules
3. skills/ — When complex multi-step workflows need standardization
4. agents/ — When tasks are complex enough to require multiple professional perspectives in parallel

Principle: "Good enough" beats "perfect". Don't build complex multi-agent systems from the start; introduce them only when truly needed.