~/.claude/
├── CLAUDE.md                       全局指令
├── settings.json                   全局设置
├── history.jsonl                   所有 session 的 prompt 历史
├── stats-cache.json                聚合使用统计（按天/按模型 token）
├── mcp-needs-auth-cache.json       MCP 待认证缓存
│
├── projects/                       每项目的会话 JSONL（含完整对话）
├── plans/                          Plan 模式生成的 .md
├── todos/                          每会话的 TodoWrite 状态
├── tasks/                          长任务追踪
├── file-history/<session-uuid>/    文件编辑前快照（撤销源）
├── debug/                          每会话 debug 日志（有 latest 软链）
├── shell-snapshots/                每会话约 50KB 的 shell 环境快照
├── session-env/                    会话环境变量
├── paste-cache/                    粘贴内容（按 hash 去重）
├── downloads/                      下载的工件
├── backups/                        自动配置备份
├── cache/                          changelog 等缓存
│
├── commands/  skills/  agents/     全局版（个人，不跟项目走）
├── output-styles/                  输出风格定义
├── rules/  hooks/                  全局规则和钩子
├── plugins/                        插件市场和已装清单
├── statsig/                        feature flag 缓存
├── telemetry/                      遥测（如启用）
├── ide/                            VS Code/Cursor 集成的 PID 锁
└── statusline.sh                   状态栏脚本（你写的）

.claude/
├── output-styles/        新（v2.0+），控制响应格式
├── worktrees/            --worktree 标志下创建的隔离工作区
├── scheduled-tasks/      定时任务（最新加入）
└── subagents/            子代理的对话记录（"sidechain"）
.worktreeinclude          项目根的特殊文件，列出哪些 gitignored
                          文件（如 .env）该被复制进新 worktree

--- description: Review current changes argument-hint: [issue-number] --- Look at issue #$ARGUMENTS:
!`gh issue view $ARGUMENTS` !`git diff main...HEAD` Now review the diff against the issue requirements.

--- description: API conventions globs: ["src/api/**", "src/handlers/**"] ---

--- name: code-reviewer description: Expert code reviewer. Use PROACTIVELY when reviewing PRs model: sonnet tools: Read, Grep, Glob ---

{ "type": "command", "command": "...", "async": true } // 跑 shell { "type": "prompt", "prompt": "Should I stop?" } // LLM 评估 { "type": "agent", "prompt": "Verify tests..." } // 派子代理 { "type": "http", "url": "..." } // webhook

claude --init # 触发 matcher: "init" 的 Setup 钩子 claude --maintenance # 触发 matcher: "maintenance" claude --init-only # 跑完就退出，适合 CI

/etc/claude-code/managed-settings.json           # Linux/macOS
C:\Program Files\ClaudeCode\managed-settings.json # Windows (2.1.75+)
managed-settings.d/                              # systemd 风格 drop-in
  ├── 10-telemetry.json
  └── 20-security.json

managed settings → CLI flags → env vars → project (.claude/) 
→ user (~/.claude/) → Claude Code defaults

{ "session_id": "abc...", "model": {"id": "claude-opus-4-6", "display_name": "Opus"}, "workspace": {"current_dir": "...", "git_worktree": "feature-xyz"}, "output_style": {"name": "default"}, "cost": {"total_cost_usd": 0.012, "total_lines_added": 156}, "context_window": {"used_percentage": 8, "context_window_size": 200000}, "rate_limits": {"five_hour": {...}, "seven_day": {...}} }

projects/<project-hash>/<uuid>.jsonl     完整对话
file-history/<uuid>/                     文件编辑快照
todos/<uuid>.json                        任务状态
debug/<uuid>.log                         调试日志
session-env/<uuid>/                      环境变量

project/
├── CLAUDE.md              # 全局架构
├── backend/CLAUDE.md      # 改后端时额外加载
└── frontend/CLAUDE.md     # 改前端时额外加载

CLAUDE.md, settings.json, .mcp.json
.claude/rules/  .claude/commands/  .claude/skills/
.claude/agents/  .claude/hooks/  .claude/output-styles/

┌─────────────────────────────────────────────────────┐
│ 工具配置层（.claude/, .cursor/ 等）                 │
│ → 给特定工具的行为配置                              │
│ → 钩子、子代理、权限                                │
├─────────────────────────────────────────────────────┤
│ 协作指令层（CLAUDE.md / AGENTS.md / harness.md 等）│
│ → 给 LLM 看的项目知识/工作流                       │
│ → 团队约定、构建命令、边界                         │
└─────────────────────────────────────────────────────┘

ln -s AGENTS.md CLAUDE.md

# Project Name ## Commands - `pnpm test` — Run test suite (required before PR) - `pnpm build` — Production build - `pnpm dev` — Dev server at localhost:3000 ## Project Structure - `src/components/` — Reusable UI - `src/features/` — Feature code ## Code Style - TypeScript everywhere - 2-space indent - Components: PascalCase ## Git Workflow - Branch: `initials/short-desc` - Title format: [<project>] <Title> ## Boundaries - **NEVER** commit `.env` or hardcode keys - **ALWAYS** run typecheck before committing - Don't touch `vendor/` or `dist/`

~/.codex/AGENTS.override.md    ← 全局，最高优先
~/.codex/AGENTS.md             ← 全局
project/AGENTS.override.md     ← 项目根
project/AGENTS.md              ← 项目根
project/services/payments/
    AGENTS.override.md         ← 子目录，覆盖父级
    AGENTS.md

project/
├── README.md                    # 给人看
├── AGENTS.md                    # 给所有 AI 工具看（→ CLAUDE.md 软链）
├── CLAUDE.md                    # Claude 专用（或软链 AGENTS.md）
├── ARCHITECTURE.md              # 架构决策
├── CONTRIBUTING.md              # PR 流程
├── docs/
│   ├── TYPESCRIPT.md            # AGENTS.md 链到这里
│   ├── TESTING.md
│   └── API.md
├── Plans.md                     # 当前计划（plan 模式产出）
├── PROGRESS.md                  # 长任务进度
├── SSOT.md                      # 真理源
├── .github/
│   ├── copilot-instructions.md  # Copilot 专用
│   └── agents/
│       ├── docs-agent.md
│       └── test-agent.md
├── .cursor/rules/               # Cursor 专用
│   └── *.mdc
└── .claude/                     # Claude Code 配置（你已经熟了）
    ├── agents/, skills/, hooks/, ...
    └── ...

packages/api/
├── AGENTS.md                    # API 包专属约定
└── CLAUDE.md                    # 同上

## TypeScript 约定 详见 [docs/TYPESCRIPT.md](./docs/TYPESCRIPT.md)

# 1. 写一份 AGENTS.md（60–150 行，六大块） # 2. 软链到 CLAUDE.md（让 Claude Code 也读） ln -s AGENTS.md CLAUDE.md # 3. 用 GitHub Copilot 的话再软链一份 mkdir -p .github && ln -s ../AGENTS.md .github/copilot-instructions.md