Skip to content

refactor(agents): enforce senior engineering principles across all agents#8

Merged
phuthuycoding merged 1 commit into
masterfrom
refactor/agent-engineering-principles
Jul 20, 2026
Merged

refactor(agents): enforce senior engineering principles across all agents#8
phuthuycoding merged 1 commit into
masterfrom
refactor/agent-engineering-principles

Conversation

@phuthuycoding

@phuthuycoding phuthuycoding commented Jul 20, 2026

Copy link
Copy Markdown
Owner

Summary

  • Add assets/architecture/_shared/engineering-principles.md — single source of truth for the senior bar every agent codes to:
    1. Simple first — never overengineer (YAGNI, complexity must be earned)
    2. Think business first (restate requirement, walk edge/failure paths, trace blast radius)
    3. Challenge the solution — fit / risk / worth it (does it suit THIS project, name risks, weigh cost vs benefit, push back before implementing)
    4. Senior-level code (explicit error handling + logging, no swallowed exceptions, ~500-line file ceiling)
    5. No garbage code (no dead code, debug leftovers, drive-by edits; reuse before writing)
    6. Comments must earn their place (only why/constraint, never narrate code)
  • Add an Engineering Principles (NON-NEGOTIABLE) block to all 16 agents, tailored per role:
    • code-reviewer treats overengineering and garbage code as defects; reviews against the pattern the codebase actually uses
    • clean-architect must right-size recommendations (no 4-layer Clean Architecture for simple CRUD)
    • refactor applies design patterns only to remove real existing complexity, never speculatively
    • perf-optimizer, security-audit, test-writer, etc. get role-specific challenge/worth-it bullets
  • Developer agents: replace "follow the architecture docs exactly" with match-the-project-first (read-project-first.md), consistent with the earlier skills refactor (92e6d0b)
  • nodejs-backend-dev: DDD layer rules apply only when the project actually uses (or is migrating to) DDD
  • Sync the Architecture References table in CLAUDE.md

Notes

  • Installer symlinks/copies the whole architecture/ folder, so the new _shared file is picked up with no installer change; --project (copy) installs need a re-run of moicle install --project.

…ents

- Add _shared/engineering-principles.md: simple first / no overengineering,
  business-first thinking, challenge fit/risk/worth, senior-level code,
  no garbage code, no valueless comments
- Add Engineering Principles (NON-NEGOTIABLE) block to all 16 agents,
  tailored per role (reviewer flags overengineering as defect, architect
  right-sizes, refactor never adds speculative patterns)
- Developer agents: replace 'follow architecture docs exactly' with
  match-the-project-first (read-project-first.md), consistent with the
  earlier skills refactor
- nodejs-backend-dev: DDD layer rules apply only when the project uses DDD
@phuthuycoding
phuthuycoding merged commit a7646fe into master Jul 20, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant