Skip to content

Commit 8f89b40

Browse files
dutterbutterdutterbutter
authored
chore: adds LLM instructions for agent development / consuming (#39)
* chore: add llm instructions * chore: add consumable llm instruction * chore: format
1 parent 8bb422d commit 8f89b40

14 files changed

+1515
-0
lines changed

‎.github/CONTRIBUTING.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,13 @@ Before submitting a PR, please make sure:
4747
- Update or add docs/examples if needed.
4848
- Link the related issue (if any).
4949

50+
## 🤖 AI-Assisted Development
51+
52+
If you're using AI tools (Claude, ChatGPT, Cursor, etc.) to contribute:
53+
54+
- Start with [`AGENTS.md`](../AGENTS.md) for rules and workflow
55+
- See [`llm/README.md`](../llm/README.md) for detailed guidance
56+
5057
## 💬 Questions?
5158

5259
- Open a [GitHub Discussion](https://github.com/ZKsync-Community-Hub/zksync-developers/discussions/)

‎AGENTS.md‎

Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
# AGENTS.md – LLM Contributing Guide
2+
3+
> **Tool-agnostic entrypoint for AI assistants working on zksync-js.**
4+
> For detailed guidance, see [`llm/README.md`](./llm/README.md).
5+
6+
---
7+
8+
## Quick Rules
9+
10+
| Do | Don't |
11+
| --------------------------------------- | ---------------------------------------------- |
12+
| Read context before editing | Invent commands or scripts |
13+
| Make small, incremental changes | Refactor unrelated code |
14+
| Preserve existing patterns | Change public APIs without updating docs/tests |
15+
| Use adapter library's encoders/decoders | Hand-roll ABI encode/decode |
16+
| Keep `core/` adapter-agnostic | Import `viem`/`ethers` in `core/` |
17+
18+
---
19+
20+
## Hard Repo Rules
21+
22+
> [!CAUTION]
23+
> These rules are **non-negotiable**.
24+
25+
1. **`core/` must NEVER depend on adapters**
26+
- No imports from `viem`, `ethers`, or adapter-specific types in `core/`
27+
- All shared logic and types live in `core/`
28+
29+
2. **Adapters are translation layers only**
30+
- `src/adapters/viem/` and `src/adapters/ethers/` translate between `core` abstractions and library calls
31+
- Use each library's native ABI encoders/decoders
32+
33+
3. **No logic duplication across adapters**
34+
- If logic is duplicated, extract to `core/` as adapter-agnostic utilities
35+
36+
---
37+
38+
## How to Work Here
39+
40+
### Before You Start
41+
42+
1. Read [`llm/repo-context.md`](./llm/repo-context.md) for architecture overview
43+
2. Identify which files you'll touch
44+
3. Check existing patterns in similar files
45+
46+
### Standard Workflow
47+
48+
1. Restate objective + constraints
49+
2. Identify files to modify
50+
3. Implement with **minimal diff**
51+
4. Run required scripts: `bun run lint`, `bun run format:check`, `bun run test`, `bun run typecheck`
52+
5. Update docs if needed: `docs/src/SUMMARY.md`, SDK reference, LLM docs
53+
54+
### Definition of Done
55+
56+
- [ ] `bun run lint` passes
57+
- [ ] `bun run format:check` passes
58+
- [ ] `bun run test` passes
59+
- [ ] `bun run typecheck` passes
60+
- [ ] Docs updated (if public-facing change)
61+
- [ ] No secrets committed
62+
63+
---
64+
65+
## When Unsure
66+
67+
```
68+
Is it about core/ vs adapters?
69+
→ Read llm/architecture-adapters-and-core.md
70+
71+
Is it about adding a new resource?
72+
→ Read llm/resource-patterns.md
73+
74+
Is it about code style?
75+
→ Read llm/style-guide.md
76+
77+
Can't find a script?
78+
→ Check package.json, never invent commands
79+
80+
Still unsure?
81+
→ Ask the user, don't guess
82+
```
83+
84+
---
85+
86+
## Minimal Diff Principle
87+
88+
- Change only what's necessary
89+
- Don't refactor adjacent code
90+
- Don't rename unless explicitly required
91+
- Don't "improve" unrelated code
92+
93+
---
94+
95+
## Key Resources
96+
97+
| Topic | File |
98+
| ------------------- | ---------------------------------------------------------------------------------- |
99+
| Index & navigation | [`llm/README.md`](./llm/README.md) |
100+
| Repo architecture | [`llm/repo-context.md`](./llm/repo-context.md) |
101+
| Core vs Adapters | [`llm/architecture-adapters-and-core.md`](./llm/architecture-adapters-and-core.md) |
102+
| Adding resources | [`llm/resource-patterns.md`](./llm/resource-patterns.md) |
103+
| Style guide | [`llm/style-guide.md`](./llm/style-guide.md) |
104+
| Testing & quality | [`llm/testing-and-quality.md`](./llm/testing-and-quality.md) |
105+
| Commit/PR checklist | [`llm/commit-and-pr.md`](./llm/commit-and-pr.md) |
106+
| Security | [`llm/security-and-secrets.md`](./llm/security-and-secrets.md) |

‎CLAUDE.md‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# CLAUDE.md – Claude-Specific Instructions
2+
3+
> **Claude entrypoint for zksync-js.**
4+
> This file supplements [`AGENTS.md`](./AGENTS.md) with Claude-specific notes.
5+
6+
---
7+
8+
## Start Here
9+
10+
1. Read [`AGENTS.md`](./AGENTS.md) for rules and workflow
11+
2. Read [`llm/README.md`](./llm/README.md) for detailed guidance
12+
3. Follow the standard workflow before making changes
13+
14+
---
15+
16+
## Claude-Specific Notes
17+
18+
- **Use tools proactively**: Read files, run scripts, verify changes
19+
- **Prefer small commits**: Make incremental, focused changes
20+
- **Verify before claiming done**: Run `bun run lint`, `bun run test`, `bun run typecheck`
21+
- **Ask when uncertain**: Don't guess at conventions or commands
22+
23+
---
24+
25+
## Key Files
26+
27+
- [`AGENTS.md`](./AGENTS.md) – Primary rules (read first)
28+
- [`llm/README.md`](./llm/README.md) – Detailed navigation
29+
- [`llm/architecture-adapters-and-core.md`](./llm/architecture-adapters-and-core.md) – Core/adapter boundary
30+
- [`llm/resource-patterns.md`](./llm/resource-patterns.md) – Adding new SDK resources

‎llm/README.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
# LLM Guidance – zksync-js
2+
3+
> **Centralized documentation for AI assistants contributing to zksync-js.**
4+
5+
---
6+
7+
## Start Here
8+
9+
Read in this order:
10+
11+
1. [`repo-context.md`](./repo-context.md) – What this repo is, architecture overview
12+
2. [`architecture-adapters-and-core.md`](./architecture-adapters-and-core.md) – Core vs adapter boundary (**critical**)
13+
3. [`style-guide.md`](./style-guide.md) – Code style and naming
14+
4. [`testing-and-quality.md`](./testing-and-quality.md) – Scripts and quality checks
15+
16+
---
17+
18+
## Common Tasks
19+
20+
| Task | Guide |
21+
|---|---|
22+
| Add a new SDK resource | [`resource-patterns.md`](./resource-patterns.md) |
23+
| Add a method to existing resource | [`resource-patterns.md`](./resource-patterns.md) + [`architecture-adapters-and-core.md`](./architecture-adapters-and-core.md) |
24+
| Update types | [`architecture-adapters-and-core.md`](./architecture-adapters-and-core.md) (types live in `core/`) |
25+
| Fix a bug | [`change-playbook.md`](./change-playbook.md) |
26+
| Submit a PR | [`commit-and-pr.md`](./commit-and-pr.md) |
27+
28+
---
29+
30+
## All Files
31+
32+
| File | Purpose |
33+
|---|---|
34+
| [`repo-context.md`](./repo-context.md) | Architecture overview, directory structure |
35+
| [`architecture-adapters-and-core.md`](./architecture-adapters-and-core.md) | Core vs adapter boundary rules |
36+
| [`resource-patterns.md`](./resource-patterns.md) | Adding new SDK resources |
37+
| [`style-guide.md`](./style-guide.md) | TypeScript code style |
38+
| [`testing-and-quality.md`](./testing-and-quality.md) | Scripts, Definition of Done |
39+
| [`change-playbook.md`](./change-playbook.md) | Standard change workflow |
40+
| [`commit-and-pr.md`](./commit-and-pr.md) | Commit/PR conventions |
41+
| [`security-and-secrets.md`](./security-and-secrets.md) | Security requirements |
42+
| [`llm-behavior.md`](./llm-behavior.md) | How the assistant should respond |
43+
| [`sdk-consumers.md`](./sdk-consumers.md) | **For agents using this SDK** (building UIs, bots) |

‎llm/architecture-adapters-and-core.md‎

Lines changed: 146 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,146 @@
1+
# Architecture: Adapters and Core
2+
3+
> **The boundary between `core/` and adapters is critical. Read this carefully.**
4+
5+
---
6+
7+
## Hard Rules
8+
9+
> [!CAUTION]
10+
> These rules are **non-negotiable**.
11+
12+
### 1. `core/` Must Never Depend on Adapters
13+
14+
```typescript
15+
// ❌ NEVER in core/
16+
import { encodeFunctionData } from 'viem';
17+
import { AbiCoder } from 'ethers';
18+
import type { Address } from 'viem';
19+
import type { Provider } from 'ethers';
20+
21+
// ✅ OK in core/
22+
import type { Hex, Address } from './types/primitives';
23+
import { ZKsyncError } from './errors';
24+
```
25+
26+
### 2. Adapters Use Their Library's Encoders/Decoders
27+
28+
```typescript
29+
// ❌ NEVER hand-roll encode/decode
30+
const encoded = '0x' + functionSelector + param1.slice(2) + param2.slice(2);
31+
32+
// ✅ Viem adapter
33+
import { encodeFunctionData, decodeFunctionResult } from 'viem';
34+
const encoded = encodeFunctionData({ abi, functionName, args });
35+
36+
// ✅ Ethers adapter
37+
import { Interface, AbiCoder } from 'ethers';
38+
const iface = new Interface(abi);
39+
const encoded = iface.encodeFunctionData(functionName, args);
40+
```
41+
42+
### 3. Shared Logic Lives in `core/`
43+
44+
If logic is duplicated across adapters, extract it to `core/`:
45+
46+
```typescript
47+
// core/utils/gas.ts
48+
export function calculateL2GasLimit(baseCost: bigint, overhead: bigint): bigint {
49+
return baseCost + overhead;
50+
}
51+
52+
// adapters/viem/resources/deposits.ts
53+
import { calculateL2GasLimit } from '../../../core/utils/gas';
54+
55+
// adapters/ethers/resources/deposits.ts
56+
import { calculateL2GasLimit } from '../../../core/utils/gas';
57+
```
58+
59+
---
60+
61+
## Adapter Responsibilities
62+
63+
Adapters are **translation layers only**. They:
64+
65+
| Do | Don't |
66+
| ------------------------------------- | -------------------------------------- |
67+
| Translate core types to library types | Contain business logic |
68+
| Call library methods (viem/ethers) | Duplicate logic across adapters |
69+
| Map library results to core types | Define new types (types live in core/) |
70+
| Handle library-specific errors | Hand-roll ABI encoding/decoding |
71+
72+
### Adapter Checklist
73+
74+
For any adapter code:
75+
76+
- [ ] Shared, adapter-agnostic logic extracted to `core/` (business logic requiring adapter imports is fine here)
77+
- [ ] Uses library's native encoding/decoding
78+
- [ ] Returns core types
79+
- [ ] Accepts core types as input (or maps from them)
80+
- [ ] Error handling wraps library errors into `ZKsyncError`
81+
82+
---
83+
84+
## Acceptable vs Unacceptable
85+
86+
### Imports in `core/`
87+
88+
```typescript
89+
// ✅ Acceptable
90+
import type { Hex, Address } from './types/primitives';
91+
import { ZKsyncError } from './errors';
92+
import { BRIDGEHUB_ABI } from './internal/abis';
93+
94+
// ❌ Unacceptable
95+
import { type Address } from 'viem';
96+
import { ethers } from 'ethers';
97+
import { encodeFunctionData } from 'viem';
98+
```
99+
100+
### Types in `core/`
101+
102+
```typescript
103+
// ✅ Core defines primitives and flow types
104+
// core/types/primitives.ts
105+
export type Address = `0x${string}`;
106+
export type Hex = `0x${string}`;
107+
export type Hash = `0x${string}`;
108+
109+
// core/types/flows/deposit.ts
110+
export interface DepositRequest {
111+
token: Address;
112+
amount: bigint;
113+
to: Address;
114+
}
115+
```
116+
117+
### Adapter Implementation
118+
119+
```typescript
120+
// ✅ Adapter translates and calls library
121+
// adapters/viem/resources/deposits.ts
122+
import { encodeFunctionData } from 'viem';
123+
import type { DepositRequest } from '../../../core/types/flows/deposit';
124+
125+
export function prepareDeposit(ctx: ViemContext, req: DepositRequest) {
126+
const data = encodeFunctionData({
127+
abi: BRIDGEHUB_ABI,
128+
functionName: 'requestL2TransactionDirect',
129+
args: [req.to, req.amount, ...],
130+
});
131+
// ...
132+
}
133+
```
134+
135+
---
136+
137+
## When to Add to Core vs Adapter
138+
139+
| Scenario | Location |
140+
| ----------------------------------- | ------------------------------- |
141+
| New type definition | `core/types/` |
142+
| New constant (address, magic value) | `core/constants.ts` |
143+
| Utility used by multiple adapters | `core/utils/` |
144+
| ABI definition | `core/internal/abis/` |
145+
| Library-specific call | Adapter |
146+
| Library-specific error handling | Adapter (wrap to `ZKsyncError`) |

0 commit comments

Comments
 (0)