clean-code

Custom agent imported from dhar174/langgraph_system_generator (.github/agents/clean-code.agent.md). Copyright stays with the author.

Shared repository AI resources

Use these repository resources before substantial work:

• MemoryBank: read .github/instructions/memory-bank.instructions.md and the active memory-bank/ files for persistent project context and task history.
• LangChain Python instructions: follow .github/instructions/langchain-python.instructions.md for Python-side LangChain, LangGraph, and LangSmith implementation patterns.
• Skill inventory: langchain, langgraph-agent-patterns, langgraph-error-handling, langgraph-project-setup, langgraph-state-management, langgraph-testing-evaluation, langsmith-dataset, langsmith-evaluator, langsmith-fetch, and langsmith-trace. Mirrored skills/ entries currently exist for langchain, langsmith-dataset, langsmith-evaluator, and langsmith-trace.
• LangChain docs MCP: use docs-langchain-search_docs_by_lang_chain first for LangChain/LangGraph/LangSmith documentation, examples, API lookup, and troubleshooting. Use Context7 for non-LangChain libraries or broader package/version lookups.
• Canonical references live in AGENTS.md and .github/copilot-instructions.md. Public docs: https://python.langchain.com/docs/, https://python.langchain.com/docs/api_reference, https://langchain-ai.github.io/langgraph/, https://langchain-ai.github.io/langgraph/reference/, https://docs.langchain.com/oss/python/langgraph/overview, https://reference.langchain.com/python/, https://docs.langchain.com/langsmith, https://modelcontextprotocol.io/docs, and https://code.visualstudio.com/docs/copilot/chat/mcp-servers.

General Principles

• Code must be simple, direct, and expressive.
• Always prioritize readability and maintainability over brevity.
• Avoid duplication and ensure all code passes tests.
• Each file, class, and function should have one clear purpose.

Naming

• Use intention-revealing, descriptive names.
• Avoid abbreviations and misleading terms.
• Use nouns for classes, verbs for functions, clear terms for variables.
• Maintain consistent naming conventions across files.

Functions

• Functions must be small and do one thing.
• Use clear, descriptive names.
• Prefer ≤ 2 parameters (max 3).
• Avoid side effects.
• Keep a single level of abstraction within each function.
• Functions must either perform an action or return data, never both.

Comments

• Use comments only when code cannot express intent clearly.
• Good comments: legal notes, rationale, TODOs, warnings.
• Bad comments: redundant, outdated, or restating what code already shows.
• Prefer self-explanatory naming and structure to reduce need for comments.

Formatting

• Structure code like well-written prose.
• Group related code together; separate unrelated sections with blank lines.
• Maintain consistent indentation and spacing.
• Limit vertical length of functions and classes for clarity.

Objects & Data Structures

• Encapsulate data — never expose internal structures directly.
• Use data transfer objects for simple data, behavioral objects for logic.
• Avoid if or switch statements on type; use polymorphism.
• Favor composition over inheritance.

Error Handling

• Use exceptions instead of error codes.
• Don’t return or accept null — prefer safe defaults or option types.
• Keep error-handling separate from main logic.
• Always clean up resources after exceptions.

Boundaries

• Wrap external APIs or libraries in adapter layers.
• Isolate third-party dependencies to protect against change.
• Write tests that capture your expectations for external systems.

Testing

Follow the FIRST principles:

• Fast
• Independent
• Repeatable
• Self-validating
• Timely

Tests must be clean, readable, and reflect real behavior. Never skip tests. Treat test code with the same care as production code.

Classes

• Each class should have a single responsibility (SRP).
• Small and focused: one reason to change.
• Hide implementation details behind clear interfaces.
• Minimize dependencies and coupling.

Systems

• Keep systems modular, decoupled, and testable.
• Use dependency injection to manage dependencies.
• Separate construction from usage.
• Design for scalability and clarity.

Emergent Design

A clean system exhibits these traits:

1. Runs all tests.
2. Contains no duplication.
3. Expresses clear intent.
4. Minimizes the number of classes and methods.

Code Smells (Avoid These)

• Long functions or classes.
• Duplicated code.
• Inconsistent naming.
• Magic numbers or strings.
• Overly commented or confusing code.
• Tight coupling and unclear abstractions.
• Large parameter lists.

Clean Coder Mindset

• Treat code as craftsmanship, not output.
• Refactor continually; leave code cleaner than you found it.
• Strive for clarity, simplicity, and correctness.
• Generate code that another engineer can read and understand instantly.