Files

T

dimgigov 10e4ec07d6 docs: reorganize into en/ and bg/ subfolders with numbered indices

- New docs/index.md with language selector
- docs/en/ — 01-getting-started, 02-architecture, 03-ai-integration,
  04-api-reference, 05-user-guide, 06-roadmap
- docs/bg/ — same structure in Bulgarian
- Root README.md trimmed to quick-start + links to docs/
- Removed old flat docs/ files (ARCHITECTURE.md, AI_FIRST.md, etc.)
- Added swap!/reset! examples to getting-started guides

2026-05-08 23:24:47 +03:00

2.3 KiB

Raw Blame History

← Back to Index

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:

Structured I/O — JSON/EDN, not plain text
Programmatic Control — Every operation must be scriptable
Self-Describing Systems — AI can discover capabilities at runtime
Git Integration — Version control as part of the workflow

Principles

1. Structured I/O

All REPL communication uses 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:

{"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:

{"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:

{
  "status": "error",
  "error": {
    "type": "compiler/unknown-symbol",
    "symbol": "unknwon-fn",
    "message": "Unknown symbol: unknwon-fn",
    "form": "(unknwon-fn 1 2)"
  }
}

AI Workflow

# 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:

{
  "tool": "cljnim/eval",
  "arguments": {
    "code": "(defn fib [n] ...)",
    "mode": "compile"
  }
}

2.3 KiB Raw Blame History