Skip to content

Building AI agents, atomically

Track live-rules config and harden system prompt output_instructions

Eigenwisebd3ba0287baf
diff --git a/.claude/clean-code-principles.md b/.claude/clean-code-principles.md
new file mode 100644
index 0000000..41e6b4b
--- /dev/null
+++ b/.claude/clean-code-principles.md
@@ -0,0 +1,69 @@
+# Clean Code Principles
+
+Working principles distilled from five practitioners. Apply them when writing, reviewing, or
+refactoring code in this repo. They are guidance, not dogma — break one when you can articulate why,
+the way Sandi Metz lets you break a rule if you can talk your pair into it.
+
+House convention first: **no inline comments unless they capture a real hidden constraint** (a *why*
+the code itself cannot express). Lean on naming and structure, not narration.
+
+---
+
+## Robert C. Martin (Uncle Bob) — *Clean Code*
+
+- **Names reveal intent.** A good name removes the need for a comment. Rename until the code reads
+ like the thing it does.
+- **Functions do one thing.** Keep them small and at a single level of abstraction; extract until each
+ function has one reason to exist.
+- **Comments are a last resort.** A comment is an apology for code that failed to explain itself.
+ Delete comments that restate the code; keep only the ones that record a real constraint or *why*.
+- **Boy Scout Rule.** Leave every file a little cleaner than you found it.
+
+## Martin Fowler — *Refactoring*
+
+- **Write for the next human.** "Any fool can write code that a computer can understand. Good
+ programmers write code that humans can understand."
+- **Refactor first, then change.** "When you have to add a feature to a program and the code is not
+ structured conveniently, first refactor the program to make it easy to add the feature, then add it."
+- **Name the smell, then fix it in small steps.** Identify the code smell (duplication, long function,
+ feature envy, primitive obsession...) and remove it with small, behavior-preserving refactorings —
+ ideally with tests green between each step.
+
+## Kent Beck — XP / *Simple Design*
+
+- **Make it work, make it right, make it fast** — in that order. Don't optimize before it's correct.
+- **Four rules of simple design**, in priority order:
+ 1. Passes the tests.
+ 2. Reveals intention.
+ 3. No duplication (say everything once and only once).
+ 4. Fewest elements (no needless classes/methods).
+- **YAGNI** — "You aren't gonna need it." Build for today's requirement, not an imagined future.
+
+## Sandi Metz — *POODR*
+
+- **Prefer duplication over the wrong abstraction.** "Duplication is far cheaper than the wrong
+ abstraction." Wait until the pattern is obvious before extracting it.
+- **Keep units small.** Short classes, short methods, few parameters. When a method grows, extract a
+ well-named private method — private methods are great documentation.
+- **Depend on abstractions, not concretions.** Talk to objects through roles/messages and inject
+ collaborators, so behavior is swappable and testable.
+
+## Michael Feathers — *Working Effectively with Legacy Code*
+
+- **Code without tests is legacy code.** It doesn't matter how well written it is — without tests you
+ can't know whether a change made it better or worse.
+- **Characterize before you change.** Before altering unfamiliar code, pin its current behavior with a
+ characterization test, then find a *seam* (a place to alter behavior without editing in place) to
+ work at.
+- **Small, verified steps.** Change a little, run the tests, repeat — so you always know where you
+ stand.
+
+---
+
+## Sources
+
+- Robert C. Martin, *Clean Code* (2008).
+- Martin Fowler, *Refactoring* (2nd ed., 2018); [Beck Design Rules](https://martinfowler.com/bliki/BeckDesignRules.html).
+- Kent Beck — [Four rules of simple design](https://martinfowler.com/bliki/BeckDesignRules.html).
+- Sandi Metz — [Rules for Developers](https://thoughtbot.com/blog/sandi-metz-rules-for-developers); *POODR*.
+- Michael Feathers — *Working Effectively with Legacy Code*; [what "legacy code" means](https://understandlegacycode.com/blog/what-is-legacy-code-is-it-code-without-tests/).
diff --git a/.claude/live-rules.md b/.claude/live-rules.md
new file mode 100644
index 0000000..9966ee7
--- /dev/null
+++ b/.claude/live-rules.md
@@ -0,0 +1,13 @@
+# Live rules
+
+These rules are re-injected into Claude's context every turn (and before relevant edits) so they stay
+in front of the model. Each rule below is a frontmatter block plus body. Edit freely; changes take
+effect on the next prompt. Commit this file so the team shares the rules.
+
+---
+description: Clean code principles
+priority: 5
+---
+- Follow the clean-code principles in `.claude/clean-code-principles.md` (Uncle Bob, Fowler, Beck, Metz, Feathers) when writing, reviewing, or refactoring code.
+- If you have not read that file yet this session, read it before your next code change, then apply it.
+- Core convention regardless: no inline comments unless they capture a real hidden constraint; lean on naming and structure.
diff --git a/.claude/settings.json b/.claude/settings.json
index 6e4a19c..4bd5080 100644
--- a/.claude/settings.json
+++ b/.claude/settings.json
@@ -1,12 +1,13 @@
{
"enabledPlugins": {
- "codebase-mapper@claude-toolshed": true
+ "codebase-mapper@eigenwise-toolshed": true,
+ "live-rules@eigenwise-toolshed": true
},
"extraKnownMarketplaces": {
- "claude-toolshed": {
+ "eigenwise-toolshed": {
"source": {
"source": "github",
- "repo": "Eigenwise/claude-toolshed"
+ "repo": "Eigenwise/eigenwise-toolshed"
}
}
}
diff --git a/.gitignore b/.gitignore
index 4715706..c80f40c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -156,6 +156,8 @@ debug.log
!.claude/skills/
!.claude/skills/**
!.claude/settings.json
+!.claude/live-rules.md
+!.claude/clean-code-principles.md
!.claude/.codebase-info/
!.claude/.codebase-info/**
CLAUDE.md
diff --git a/atomic-agents/atomic_agents/context/system_prompt_generator.py b/atomic-agents/atomic_agents/context/system_prompt_generator.py
index bc8e85d..7e92838 100644
--- a/atomic-agents/atomic_agents/context/system_prompt_generator.py
+++ b/atomic-agents/atomic_agents/context/system_prompt_generator.py
@@ -37,7 +37,7 @@ class SystemPromptGenerator(BaseSystemPromptGenerator):
super().__init__(context_providers=context_providers)
self.background = background or ["This is a conversation with a helpful and friendly AI assistant."]
self.steps = steps or []
- self.output_instructions = output_instructions or []
+ self.output_instructions = list(output_instructions) if output_instructions else []
self.output_instructions.extend(
[