Skip to content

Commit 666c8d0

Browse files
qorzjqorzj
committed
feat: add .deepcode/AGENTS.md
1 parent 867ff96 commit 666c8d0

1 file changed

Lines changed: 101 additions & 0 deletions

File tree

‎.deepcode/AGENTS.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Repository Guidelines
2+
3+
## Project Structure & Module Organization
4+
5+
```
6+
src/
7+
├── cli.tsx # Entry point — parses args, renders Ink App
8+
├── session.ts # SessionManager — LLM loop, compaction, tool orchestration
9+
├── settings.ts # Settings resolution from ~/.deepcode/settings.json
10+
├── prompt.ts # System prompt builder, tool definitions, agent-drift-guard skill
11+
├── model-capabilities.ts # Model detection and thinking-mode defaults
12+
├── ui/
13+
│ ├── App.tsx # Root Ink component — state, routing, session orchestration
14+
│ ├── PromptInput.tsx # Multi-line input with slash commands, image paste, skills
15+
│ ├── MessageView.tsx # Renders assistant/tool messages with markdown
16+
│ ├── SessionList.tsx # Session picker for /resume
17+
│ └── ...
18+
├── tools/
19+
│ ├── executor.ts # ToolExecutor — dispatches tool calls to handlers
20+
│ ├── bash-handler.ts # Executes shell commands
21+
│ ├── read-handler.ts # Reads files and images
22+
│ ├── write-handler.ts # Creates/overwrites files
23+
│ ├── edit-handler.ts # Scoped string replacements in files
24+
│ ├── web-search-handler.ts # Web search tool
25+
│ └── ask-user-question-handler.ts # Interactive user prompts
26+
├── tests/ # Test suite — one *.test.ts per module
27+
docs/
28+
├── tools/ # Tool descriptions fed to the LLM
29+
├── prompts/ # EJS templates (e.g., init_command.md.ejs)
30+
dist/ # Bundled CLI output (gitignored)
31+
```
32+
33+
## Build, Test, and Development Commands
34+
35+
| Command | Purpose |
36+
|---|---|
37+
| `npm run typecheck` | TypeScript type checking (`tsc --noEmit`) |
38+
| `npm run lint` | ESLint across `src/` |
39+
| `npm run lint:fix` | ESLint with auto-fix |
40+
| `npm run format` | Prettier on all `src/**/*.{ts,tsx}` |
41+
| `npm run format:check` | Prettier in check-only mode |
42+
| `npm run check` | Runs typecheck + lint + format:check together |
43+
| `npm run bundle` | esbuild bundles `src/cli.tsx` → `dist/cli.js` (ESM, Node 18) |
44+
| `npm run build` | `check` + `bundle` — full CI gate before publish |
45+
| `npm test` | Runs all tests via `tsx --test src/tests/*.test.ts` |
46+
| `npm run test:single -- <file>` | Run a single test file (e.g., `npm run test:single -- src/tests/session.test.ts`) |
47+
48+
Run the CLI locally for manual testing: `node dist/cli.js` (after `npm run bundle`).
49+
50+
## Coding Style & Naming Conventions
51+
52+
- **Indentation**: 2 spaces, no tabs
53+
- **Quotes**: Double quotes (`"`)
54+
- **Semicolons**: Required
55+
- **Trailing commas**: `es5` (objects, arrays, etc.)
56+
- **Line width**: 120 characters max
57+
- **Line endings**: LF only
58+
59+
**TypeScript**: Strict mode enabled. Use `import type` for type-only imports (enforced by `@typescript-eslint/consistent-type-imports`). Unused variables prefixed with `_` are allowed.
60+
61+
**Formatting/Linting**: Prettier + ESLint (typescript-eslint, react-hooks). Run `npm run check` before pushing. On commit, Husky + lint-staged auto-formats staged `*.{ts,tsx,js,mjs,cjs,ejs,jsx}` and `*.json` files.
62+
63+
**File naming**: `kebab-case.ts` for modules, `kebab-case.tsx` for React/Ink components. Test files: `*.test.ts`.
64+
65+
## Testing Guidelines
66+
67+
- **Framework**: Node.js native test runner (`node:test`) with `tsx` for TypeScript
68+
- **Assertions**: `node:assert/strict`
69+
- **Coverage**: Target meaningful unit tests for core logic (session management, tool handlers, settings resolution, prompt buffer). Test files are in `src/tests/` matching the source module name.
70+
- **Test naming**: `describe`/`test` blocks with descriptive names. Example: `test("SessionManager preserves structured system content when building OpenAI messages", ...)`
71+
- **Relaxed lint rules**: Test files allow `any` and unused vars.
72+
- Run all tests with `npm test` before submitting a PR.
73+
74+
## Commit & Pull Request Guidelines
75+
76+
**Commit messages** follow conventional commits. From the project history:
77+
78+
- `feat:` — new feature (e.g., `feat: add /model command`)
79+
- `fix:` — bug fix (e.g., `fix(ui): redraw cleanly after terminal resize`)
80+
- `chore:` — tooling, deps, hooks (e.g., `chore: add husky + lint-staged`)
81+
- `refactor:` — code restructuring (e.g., `refactor(ui): optimize App hooks`)
82+
- `style:` — formatting-only changes
83+
84+
**Pull requests** should include:
85+
- A clear description of what changed and why
86+
- Link to related issue(s) if applicable
87+
- Screenshots or terminal recordings for UI changes
88+
- All checks passing (`npm run check && npm test`)
89+
- No unintended changes to `dist/` or `package-lock.json` without justification
90+
91+
## Architecture Overview
92+
93+
The CLI renders a terminal UI using [Ink](https://github.com/vadimdemedes/ink) (React for terminals). `SessionManager` drives the LLM interaction loop: it builds system prompts, sends user messages with optional skills/images, streams responses, executes tool calls via `ToolExecutor`, and compacts context when token thresholds are exceeded (512K for DeepSeek V4 models, 128K for others).
94+
95+
Six tools are available to the LLM: `bash`, `read`, `write`, `edit`, `AskUserQuestion`, and `WebSearch`. Tool definitions are registered in `src/tools/executor.ts` and described to the LLM via `src/prompt.ts` and `docs/tools/`.
96+
97+
## Agent-Specific Instructions
98+
99+
- **AGENTS.md loading**: The CLI loads agent instructions from `./AGENTS.md`, `./.deepcode/AGENTS.md`, or `~/.deepcode/AGENTS.md` (first found wins). Write project-specific guidance for the LLM in any of these.
100+
- **Skills**: Place skill definitions in `~/.agents/skills/<name>/SKILL.md` (user-level) or `./.agents/skills/<name>/SKILL.md` (project-level). Legacy path `./.deepcode/skills/` is also supported. Each SKILL.md uses YAML frontmatter with `name` and `description` fields.
101+
- The built-in `agent-drift-guard` skill is always injected into every session.

0 commit comments

Comments
 (0)