Every project carries invisible knowledge—the why behind decisions, the context of choices, the reasoning that shaped the code. This framework makes that knowledge explicit and accessible to both humans and machines.

./contextos/
├── shared/     # Team-accessible context (tracked by git)
└── self/       # Private context (gitignored)

Documentation meant for collective understanding. Contains:

• Project philosophy and goals
• Technical decisions and trade-offs
• Domain knowledge and business logic
• Collaboration guidelines
• Historical context of important changes

Personal working context. Contains:

• Individual notes and observations
• Experimental ideas not ready for sharing
• Personal reminders and TODOs
• API keys and sensitive configurations
• Local development preferences

Each file within /contextos describes a crucial piece of the project's machinery. Think of them as gears in a clockwork—each one essential, interconnected, and purposeful.

/shared/architecture.md - Why we chose this structure
/shared/domain.md - Business logic explained for future developers
/shared/decisions.md - Record of technical choices and their rationale
/self/experiments.md - Personal exploration notes
/self/local.md - Machine-specific setup details

This framework embodies the iterator philosophy: each cycle of development adds layers of understanding. Context accumulates, evolves, and serves as the memory of our creative process.

1. Create the context structure:

mkdir -p contextos/shared contextos/self
echo "contextos/self/" >> .gitignore

2. Start documenting:

echo "# Project Philosophy" > contextos/shared/philosophy.md
echo "# Local Notes" > contextos/self/notes.md

3. Make it a practice: Before each significant change, update the relevant context.

• For humans: Onboarding becomes self-guided. Decisions are traceable. Knowledge persists beyond individual memory.
• For machines: LLMs can understand not just what the code does, but why it exists and how it should evolve.
• For the future: Every project becomes a teaching artifact, a record of thought made tangible.

contextos is the bridge between intention and implementation.

A Taller Oliva Tool