dimgigov
32dbd1fc5d
- Remove leading blank line and --- separator before H1 in 03-ai-integration.md (EN + BG) to prevent markdown rendering issues - Fix broken language switcher links in en/index.md and bg/index.md - Add documentation TOC tables to both index files for proper navigation
110 lines
2.3 KiB
Markdown
110 lines
2.3 KiB
Markdown
[← Back to Index](index.md)
|
|
|
|
# AI-First Design Philosophy
|
|
|
|
## Why AI-First?
|
|
|
|
Modern software development is increasingly done by **AI agents** operating in terminal environments. These agents do not use GUIs, IDEs, or syntax highlighting. They need:
|
|
|
|
1. **Structured I/O** — JSON/EDN, not plain text
|
|
2. **Programmatic Control** — Every operation must be scriptable
|
|
3. **Self-Describing Systems** — AI can discover capabilities at runtime
|
|
4. **Git Integration** — Version control as part of the workflow
|
|
|
|
## Principles
|
|
|
|
### 1. Structured I/O
|
|
|
|
All REPL communication uses JSON:
|
|
|
|
```json
|
|
// Input
|
|
{"op": "eval", "form": "(+ 1 2)", "request-id": "uuid"}
|
|
|
|
// Output
|
|
{
|
|
"status": "ok",
|
|
"request-id": "uuid",
|
|
"result": {"type": "int", "value": 3, "printed": "3"},
|
|
"meta": {"ms": 0.5, "ns": "user"}
|
|
}
|
|
```
|
|
|
|
### 2. Batch Operations
|
|
|
|
AI agents evaluate multiple forms at once:
|
|
|
|
```json
|
|
{"op": "eval-batch",
|
|
"forms": [
|
|
"(defn add [a b] (+ a b))",
|
|
"(add 10 20)"
|
|
]}
|
|
```
|
|
|
|
### 3. Session Persistence
|
|
|
|
Definitions persist within a REPL session, allowing incremental development:
|
|
|
|
```json
|
|
{"op": "eval", "form": "(defn square [x] (* x x))"}
|
|
{"op": "eval", "form": "(square 5)"}
|
|
{"op": "get-defs"}
|
|
```
|
|
|
|
### 4. Error Recovery
|
|
|
|
All errors are structured with type, message, and context:
|
|
|
|
```json
|
|
{
|
|
"status": "error",
|
|
"error": {
|
|
"type": "compiler/unknown-symbol",
|
|
"symbol": "unknwon-fn",
|
|
"message": "Unknown symbol: unknwon-fn",
|
|
"form": "(unknwon-fn 1 2)"
|
|
}
|
|
}
|
|
```
|
|
|
|
## AI Workflow
|
|
|
|
```bash
|
|
# 1. Clone repo
|
|
git clone git@gitlab.com:balvatar/lisp-nim.git
|
|
cd lisp-nim
|
|
|
|
# 2. Start AI REPL
|
|
cljnim repl --json
|
|
|
|
# 3. AI evaluates forms, gets structured responses
|
|
# 4. AI writes files via (file/write ...) [future]
|
|
# 5. AI commits via (git/commit ...) [future]
|
|
# 6. AI pushes via (git/push) [future]
|
|
```
|
|
|
|
## Comparison
|
|
|
|
| Aspect | Human IDE | AI Terminal |
|
|
|---|---|---|
|
|
| Interface | GUI + mouse | Text + commands |
|
|
| Navigation | Clicking | `(apropos ...)`, `(doc ...)` |
|
|
| Refactoring | Manual | Batch eval + git diff |
|
|
| Testing | Run button | `(run-tests)` structured response |
|
|
| Commit | GUI dialog | `(git/commit "msg")` |
|
|
|
|
## Future: Tool-Call Format
|
|
|
|
Direct integration with AI frameworks:
|
|
|
|
```json
|
|
{
|
|
"tool": "cljnim/eval",
|
|
"arguments": {
|
|
"code": "(defn fib [n] ...)",
|
|
"mode": "compile"
|
|
}
|
|
}
|
|
```
|