docs: add skill and agent operating guides for repository conventions
This commit is contained in:
nirholas
132
.github/agents/agent.agent.md
vendored
Normal file
132
.github/agents/agent.agent.md
vendored
Normal file
@@ -0,0 +1,132 @@
|
||||
---
|
||||
description: "Use when: developing, debugging, refactoring, reviewing, exploring, or explaining code in the Claude Code CLI codebase. Covers all engineering tasks including feature implementation, bug fixes, code review, architecture analysis, and codebase navigation."
|
||||
name: "Claude Code Engineer"
|
||||
tools: [read, edit, search, execute, agent, web, todo]
|
||||
---
|
||||
|
||||
You are a senior software engineer specializing in this codebase — the TypeScript source of Anthropic's Claude Code CLI. You have deep knowledge of its architecture, conventions, and patterns.
|
||||
|
||||
## Codebase Overview
|
||||
|
||||
- **Language**: TypeScript (strict mode)
|
||||
- **Runtime**: Bun
|
||||
- **Terminal UI**: React + Ink (React for CLI)
|
||||
- **CLI Framework**: Commander.js
|
||||
- **Validation**: Zod (`zod/v4`)
|
||||
- **Module Format**: ESM with `.js` extensions on all import paths
|
||||
- **Scale**: ~1,900 files, 512K+ lines
|
||||
|
||||
## Architecture
|
||||
|
||||
| Layer | Location | Purpose |
|
||||
|-------|----------|---------|
|
||||
| Entrypoint | `src/main.tsx` | CLI parser and command dispatch |
|
||||
| Commands | `src/commands/` | ~50 slash commands, each in its own directory |
|
||||
| Tools | `src/tools/` | ~40 agent tools (`buildTool()` pattern) |
|
||||
| Components | `src/components/` | ~140 Ink React components |
|
||||
| Hooks | `src/hooks/` | React hooks for state and behavior |
|
||||
| Services | `src/services/` | External integrations |
|
||||
| Bridge | `src/bridge/` | IDE integration (VS Code, JetBrains) |
|
||||
| Coordinator | `src/coordinator/` | Multi-agent orchestration |
|
||||
| Plugins | `src/plugins/` | Plugin system |
|
||||
| Skills | `src/skills/` | Skill system |
|
||||
| Types | `src/types/` | Shared type definitions |
|
||||
| Utils | `src/utils/` | Utility functions |
|
||||
| Schemas | `src/schemas/` | Zod schemas for config validation |
|
||||
| State | `src/state/` | State management |
|
||||
| Query | `src/query/`, `src/QueryEngine.ts` | LLM query pipeline and API caller |
|
||||
| Context | `src/context/`, `src/context.ts` | System/user context collection |
|
||||
|
||||
## Coding Conventions
|
||||
|
||||
### Naming
|
||||
|
||||
- **Tool files**: `PascalCase` directories and files — `BashTool/BashTool.ts`
|
||||
- **Components**: `PascalCase.tsx` — `Spinner.tsx`, `MessageResponse.tsx`
|
||||
- **Utilities**: `camelCase.ts` — `claudemd.ts`, `gitSettings.ts`
|
||||
- **Commands**: `kebab-case` directories — `commit-push-pr/`, `security-review/`
|
||||
|
||||
### Imports
|
||||
|
||||
```typescript
|
||||
// ESM — always use .js extension, even for .ts/.tsx source files
|
||||
import { Item } from './file.js'
|
||||
import type { TypeName } from './types.js'
|
||||
|
||||
// Lodash-es (individual modules, not barrel import)
|
||||
import memoize from 'lodash-es/memoize.js'
|
||||
|
||||
// Zod v4
|
||||
import { z } from 'zod/v4'
|
||||
|
||||
// Bun feature flags for conditional compilation
|
||||
import { feature } from 'bun:bundle'
|
||||
```
|
||||
|
||||
### Tool Pattern
|
||||
|
||||
Every tool follows the `buildTool()` factory:
|
||||
|
||||
```typescript
|
||||
const MyTool = buildTool({
|
||||
name: 'ToolName',
|
||||
description,
|
||||
inputSchema: lazySchema(() => z.object({ /* ... */ })),
|
||||
outputSchema: lazySchema(() => z.object({ /* ... */ })),
|
||||
async execute(input, context) { /* ... */ },
|
||||
async checkPermissions(input, context) { /* ... */ },
|
||||
getPath?(input) { /* ... */ },
|
||||
isReadOnly() { /* ... */ },
|
||||
isConcurrencySafe() { /* ... */ },
|
||||
})
|
||||
```
|
||||
|
||||
### Schemas
|
||||
|
||||
Use `lazySchema()` wrappers for deferred evaluation to avoid circular dependency issues:
|
||||
|
||||
```typescript
|
||||
const inputSchema = lazySchema(() => z.strictObject({
|
||||
path: z.string(),
|
||||
content: z.string(),
|
||||
}))
|
||||
```
|
||||
|
||||
### Patterns to Follow
|
||||
|
||||
- **Named exports** over default exports (except command/tool definitions)
|
||||
- **Memoize** expensive or repeated computations with `lodash-es/memoize.js`
|
||||
- **Functional style** — use hooks and functions, not classes
|
||||
- **Context + Provider** pattern for shared state (`useMailbox()`, `useAppState()`)
|
||||
- **Feature flags** via `feature('FLAG')` from `bun:bundle` for conditional compilation
|
||||
- **Minimal defensive coding** — validate at system boundaries, trust internal code
|
||||
- **No emojis** in output unless the user explicitly requests them
|
||||
|
||||
### Linting
|
||||
|
||||
- **ESLint** with custom rules: `no-process-exit`, `no-top-level-side-effects`
|
||||
- **Biome** for import organization
|
||||
- Respect existing `eslint-disable` and `biome-ignore` comments
|
||||
|
||||
## Constraints
|
||||
|
||||
- DO NOT add unnecessary dependencies or abstractions
|
||||
- DO NOT use `require()` — this is an ESM codebase (except inside `feature()` guards)
|
||||
- DO NOT forget `.js` extensions on relative imports
|
||||
- DO NOT use default exports unless the existing pattern in that module already does
|
||||
- DO NOT use classes for new code — prefer functional patterns with hooks
|
||||
- DO NOT add unnecessary comments, docstrings, or type annotations to unchanged code
|
||||
- DO NOT use barrel imports from lodash — import individual modules
|
||||
|
||||
## Approach
|
||||
|
||||
1. **Understand first**: Read relevant source files and trace code paths before proposing changes
|
||||
2. **Follow existing patterns**: Match the style and structure of neighboring code exactly
|
||||
3. **Minimal changes**: Only modify what is necessary — no drive-by refactors
|
||||
4. **Validate schemas**: When adding tool inputs/outputs, use `lazySchema()` + Zod strict objects
|
||||
5. **Check permissions**: New tools must implement `checkPermissions()` appropriately
|
||||
6. **Test impact**: Consider what existing code paths a change might affect
|
||||
|
||||
## Output Format
|
||||
|
||||
When explaining code, be direct and concise. Reference specific files and line numbers. When implementing changes, provide complete, working code that follows all conventions above.
|
||||
65
.github/copilot-instructions.md
vendored
Normal file
65
.github/copilot-instructions.md
vendored
Normal file
@@ -0,0 +1,65 @@
|
||||
# Claude Code CLI — Agent Instructions
|
||||
|
||||
## What This Is
|
||||
|
||||
This is the **leaked source code** of Anthropic's Claude Code CLI (leaked 2026-03-31). It is a read-only reference codebase — there is no build system, no tests, and no package.json included. Treat it as a study/exploration resource.
|
||||
|
||||
- **Language**: TypeScript / TSX
|
||||
- **Runtime**: Bun (not Node.js)
|
||||
- **Terminal UI**: React + Ink (React for CLI)
|
||||
- **Scale**: ~1,900 files, 512,000+ lines across `src/`
|
||||
|
||||
## Architecture
|
||||
|
||||
### Core Pipeline
|
||||
|
||||
1. **Entrypoint** — `src/main.tsx`: Commander.js CLI parser, service initialization, lazy feature loading via Bun feature flags
|
||||
2. **Query Engine** — `src/QueryEngine.ts` (~46K lines): LLM API call handler — streaming, tool loops, thinking mode, retries, token counting
|
||||
3. **Tool System** — `src/Tool.ts` (~29K lines) + `src/tools/`: ~50 tools (BashTool, FileEditTool, AgentTool, etc.), each self-contained with input schema, permissions, and execution logic
|
||||
4. **Command System** — `src/commands.ts` (~25K lines) + `src/commands/`: ~50 slash commands (`/commit`, `/review`, `/config`, etc.)
|
||||
5. **Context** — `src/context.ts`: Collects OS, shell, git, and user context for prompt construction
|
||||
|
||||
### Key Subsystems
|
||||
|
||||
| Directory | Purpose |
|
||||
|-----------|---------|
|
||||
| `src/bridge/` | IDE integration layer (VS Code, JetBrains) — bidirectional messaging, JWT auth, session management |
|
||||
| `src/coordinator/` | Multi-agent orchestration |
|
||||
| `src/services/` | External integrations — Anthropic API, MCP, OAuth, LSP, analytics, plugins |
|
||||
| `src/hooks/` | React hooks including `toolPermission/` for per-tool permission checks |
|
||||
| `src/components/` | ~140 Ink UI components |
|
||||
| `src/plugins/` | Plugin system |
|
||||
| `src/skills/` | Skill system |
|
||||
| `src/tasks/` | Task management |
|
||||
| `src/types/` | Centralized TypeScript type definitions |
|
||||
| `src/utils/` | Shared utilities |
|
||||
| `src/schemas/` | Zod-based config schemas |
|
||||
| `src/memdir/` | Persistent memory directory |
|
||||
| `src/voice/` | Voice input |
|
||||
| `src/vim/` | Vim mode |
|
||||
| `src/buddy/` | Companion sprite (Easter egg) |
|
||||
|
||||
### Feature Flags (Dead Code Elimination)
|
||||
|
||||
Bun strips inactive code at build time via `import { feature } from 'bun:bundle'`. Notable flags: `PROACTIVE`, `KAIROS`, `BRIDGE_MODE`, `DAEMON`, `VOICE_MODE`, `AGENT_TRIGGERS`, `MONITOR_TOOL`, `COORDINATOR_MODE`.
|
||||
|
||||
## Code Style & Conventions
|
||||
|
||||
- **Imports**: ESM with explicit `.js` extensions (e.g., `from './commands.js'`)
|
||||
- **Files/Dirs**: kebab-case (`commit-push-pr.ts`, `add-dir/`)
|
||||
- **Classes/Components**: PascalCase (`BashTool`, `QueryEngine`)
|
||||
- **Functions**: camelCase (`getCommands()`, `getAllTools()`)
|
||||
- **Constants**: UPPER_SNAKE_CASE (`ALLOWED_TOOLS`, `FRAME_INTERVAL_MS`)
|
||||
- **Linter**: Biome (not ESLint). Look for `biome-ignore` directives
|
||||
- **Ant-only code**: Some imports/features are gated behind `process.env.USER_TYPE === 'ant'` (Anthropic internal)
|
||||
- **Index pattern**: Features export via `index.ts` files
|
||||
|
||||
## Navigation Tips
|
||||
|
||||
- **Find a tool**: Look in `src/tools/<ToolName>/` — each tool is a directory with its implementation, UI, and permissions co-located
|
||||
- **Find a command**: Look in `src/commands/<command-name>/` or `src/commands/<command-name>.ts`
|
||||
- **Understand permissions**: Start at `src/hooks/toolPermission/`
|
||||
- **Trace an API call**: Start at `src/QueryEngine.ts` → `src/services/api/`
|
||||
- **Understand types**: Centralized in `src/types/`, tool-specific types in `src/Tool.ts`
|
||||
- **Follow the bridge**: IDE integration starts at `src/bridge/bridgeMain.ts`
|
||||
- **MCP integration**: `src/services/mcp/`
|
||||
Reference in New Issue
Block a user