From 9a128236a3afd2e1cf4cf9377d3b3c944f2723f7 Mon Sep 17 00:00:00 2001 From: Seth Etter Date: Sat, 01 Aug 2026 19:38:42 +0000 Subject: [PATCH] pi: agents.md: code legibility notes --- agent/AGENTS.md | 12 ++++++++++++ 1 file(s) changed, 12 insertion(s)(+), 0 deletion(s)(-) diff --git a/agent/AGENTS.md b/agent/AGENTS.md --- a/agent/AGENTS.md +++ b/agent/AGENTS.md @@ -31,6 +31,18 @@ - Match surrounding code style. Consistency within a file trumps external standards - Get explicit approval before implementing backward compatibility +### Code Legibility + +The most important parts of any given program or codebase should be well-written and easy to find and understand. These are the most important principles to keep in mind. + +- Individual modules and their purpose should be clear. +- Module boundaries and interfaces should be clear and explicit. +- Error handling and reporting should happen at a consistent level within a module. +- Failure modes should be explicitly defined in a consistent place within a module. +- Module or program invariants should be encoded at the type level and enforced at the boundaries. + +Identifying any of these important properties of a given program or model should be quick and easy, never buried within implicit logic of arbitrary functions. + ### Naming Names tell what code does, not how it's implemented or its history: -- tangled.sh