Literate Agent
jingtaozf/literate-agent
Programação letrada com Org-mode como single source of truth
Ver no GitHubFramework para programação letrada que integra documentação Org-mode como fonte de verdade única. Permite manter código e explicações sincronizados através de tangling automático, ideal para projetos que priorizam clareza e manutenibilidade através de narrativa técnica.
Instalação
npx convez-ai jingtaozf/literate-agent1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Documentar arquitetura de sistema mantendo código e prosa sincronizados
- Implementar fluxos complexos onde a explicação do 'por quê' é tão importante quanto o código
- Gerenciar repositórios multi-submodule com narrativas técnicas coerentes
Veredito

Ferramenta sofisticada para engenheiros sênior que valorizam documentação viva. Exige mentalidade prose-first e familiaridade com Org-mode, mas resolve genuinamente o problema de divergência entre código e explicação em projetos complexos.
README
A tradução para o português deste README ainda está na fila.
-- Mode: POLY-ORG; indent-tabs-mode: nil; -- ---
#+TITLE: literate-programming meta-repo #+OPTIONS: tex:verbatim toc:nil \n:nil @:t ::t |:t ^:nil -:t f:t *:t <:t #+STARTUP: noindent
- Why this file exists
Front door of this literate-programming meta-repo. A senior engineer landing here should be able to leave with three things settled: (1) what this repo is, (2) which submodule owns the problem they came for, and (3) where to read next.
This README is auto-generated by =~/projects/literate-agent/scripts/build_overviews.py= from the bucket
- narrative config at =.literate-agent/buckets.toml=. Hand-edits
will be overwritten on the next
make build-readme.
- What this is
A literate-programming meta-repo. Production source for each submodule under =repos/= is authored prose-first as Org-mode under =lp//*.org=, then tangled back into the matching submodule's source files. Read the .org for the why; the tangled file exists for tooling that doesn't speak Org.
- How submodules relate
0 submodules configured (see =.literate-agent/buckets.toml=):
(no buckets configured yet — populate .literate-agent/buckets.toml.)
- Read order for newcomers
- This file — front-door overview.
- =CLAUDE.md= — the agent-only layer at the root.
- =lp/INDEX.org= — auto-generated catalogue.
- =lp//README.org= — per-submodule entry.
- =lp//.org= — individual literate source; tangles to =repos//<…>=. Edit here, never the tangled file.
- Top-level Org files
- [[file:lp/INDEX.org][lp/INDEX.org]] — auto-generated cross-submodule index. Regenerate
via
make build-index. - [[file:lp/draft.org][lp/draft.org]] — open design proposals queue (if used).
- [[file:lp/decisions-log.org][lp/decisions-log.org]] — accepted / rejected design proposals + research notes (if used).
- Build + lint commands
These targets are provided by templates/Makefile.lp.mk from
=literate-agent=. Drop the snippet into your project's =Makefile=:
#+begin_src bash include $(HOME)/projects/literate-agent/templates/Makefile.lp.mk #+end_src
Then:
#+begin_src bash make tangle FILE=lp//.org # tangle one .org back to repos// make tangle-all # every non-underscore lp/**/*.org
make check-structure # depth ≤ 5, prose-before-src make build-index # regenerate lp/INDEX.org make build-readme # regenerate this file + lp//README.org make build-tangle-map # refresh .cache/tangle-map.tsv #+end_src