Skip to content

The agent engineering platform.

chore: update copilot development guidelines for clarity and structure (#32230)

Mason Daugherty6f3169eb49e9
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
index bc3e4ab06b..b12f23edb2 100644
--- a/.github/copilot-instructions.md
+++ b/.github/copilot-instructions.md
@@ -1,72 +1,116 @@
-### 1. Avoid Breaking Changes (Stable Public Interfaces)
+# Global Development Guidelines for LangChain Projects
-* Carefully preserve **function signatures**, argument positions, and names for any exported/public methods.
-* Be cautious when **renaming**, **removing**, or **reordering** arguments — even small changes can break downstream consumers.
-* Use keyword-only arguments or clearly mark experimental features to isolate unstable APIs.
+## Core Development Principles
-Bad:
+### 1. Maintain Stable Public Interfaces ⚠️ CRITICAL
+
+**Always attempt to preserve function signatures, argument positions, and names for exported/public methods.**
+
+❌ **Bad - Breaking Change:**
```python
def get_user(id, verbose=False): # Changed from `user_id`
+ pass
```
-Good:
+✅ **Good - Stable Interface:**
```python
-def get_user(user_id: str, verbose: bool = False): # Maintains stable interface
+def get_user(user_id: str, verbose: bool = False) -> User:
+ """Retrieve user by ID with optional verbose output."""
+ pass
```
-🧠 *Ask yourself:* “Would this change break someone's code if they used it last week?”
+**Before making ANY changes to public APIs:**
----
+- Check if the function/class is exported in `__init__.py`
+- Look for existing usage patterns in tests and examples
+- Use keyword-only arguments for new parameters: `*, new_param: str = "default"`
+- Mark experimental features clearly with docstring warnings (using reStructuredText, like `.. warning::`)
+
+🧠 *Ask yourself:* "Would this change break someone's code if they used it last week?"
-### 2. Simplify Code and Use Clear Variable Names
+### 2. Code Quality Standards
-* Prefer descriptive, **self-explanatory variable names**. Avoid overly short or cryptic identifiers.
-* Break up overly long or deeply nested functions for **readability and maintainability**.
-* Avoid unnecessary abstraction or premature optimization.
-* All generated Python code must include type hints and return types.
+**All Python code MUST include type hints and return types.**
-Bad:
+❌ **Bad:**
```python
def p(u, d):
return [x for x in u if x not in d]
```
-Good:
+✅ **Good:**
```python
-def filter_unknown_users(users: List[str], known_users: Set[str]) -> List[str]:
+def filter_unknown_users(users: list[str], known_users: set[str]) -> list[str]:
+ """Filter out users that are not in the known users set.
+
+ Args:
+ users: List of user identifiers to filter.
+ known_users: Set of known/valid user identifiers.
+
+ Returns:
+ List of users that are not in the known_users set.
+ """
return [user for user in users if user not in known_users]
```
----
+**Style Requirements:**
-### 3. Ensure Unit Tests Cover New and Updated Functionality
+- Use descriptive, **self-explanatory variable names**. Avoid overly short or cryptic identifiers.
+- Attempt to break up complex functions (>20 lines) into smaller, focused functions where it makes sense
+- Avoid unnecessary abstraction or premature optimization
+- Follow existing patterns in the codebase you're modifying
-* Every new feature or bugfix should be **covered by a unit test**.
-* Test edge cases and failure conditions.
-* Use `pytest`, `unittest`, or the project’s existing framework consistently.
+### 3. Testing Requirements
-Checklist:
+**Every new feature or bugfix MUST be covered by unit tests.**
-* [ ] Does the test suite fail if your new logic is broken?
-* [ ] Are all expected behaviors exercised (happy path, invalid input, etc)?
-* [ ] Do tests use fixtures or mocks where needed?
+**Test Organization:**
----
+- Unit tests: `tests/unit_tests/` (no network calls allowed)
+- Integration tests: `tests/integration_tests/` (network calls permitted)
+- Use `pytest` as the testing framework
+
+**Test Quality Checklist:**
+
+- [ ] Tests fail when your new logic is broken
+- [ ] Happy path is covered
+- [ ] Edge cases and error conditions are tested
+- [ ] Use fixtures/mocks for external dependencies
+- [ ] Tests are deterministic (no flaky tests)
+
+Checklist questions:
+
+- [ ] Does the test suite fail if your new logic is broken?
+- [ ] Are all expected behaviors exercised (happy path, invalid input, etc)?
+- [ ] Do tests use fixtures or mocks where needed?
+
+```python
+def test_filter_unknown_users():
+ """Test filtering unknown users from a list."""
+ users = ["alice", "bob", "charlie"]
+ known_users = {"alice", "bob"}
-### 4. Look for Suspicious or Risky Code
+ result = filter_unknown_users(users, known_users)
-* Watch out for:
+ assert result == ["charlie"]
+ assert len(result) == 1
+```
+
+### 4. Security and Risk Assessment
- * Use of `eval()`, `exec()`, or `pickle` on user-controlled input.
- * Silent failure modes (`except: pass`).
- * Unreachable code or commented-out blocks.
- * Race conditions or resource leaks (file handles, sockets, threads).
+**Security Checklist:**
-Bad:
+- No `eval()`, `exec()`, or `pickle` on user-controlled input
+- Proper exception handling (no bare `except:`) and use a `msg` variable for error messages
+- Remove unreachable/commented code before committing
+- Race conditions or resource leaks (file handles, sockets, threads).
+- Ensure proper resource cleanup (file handles, connections)
+
+❌ **Bad:**
```python
def load_config(path):
@@ -74,7 +118,7 @@ def load_config(path):
return eval(f.read()) # ⚠️ Never eval config
```
-Good:
+✅ **Good:**
```python
import json
@@ -84,68 +128,198 @@ def load_config(path: str) -> dict:
return json.load(f)
```
----
-
-### 5. Use Google-Style Docstrings (with Args section)
+### 5. Documentation Standards
-* All public functions should include a **Google-style docstring**.
-* Include an `Args:` section where relevant.
-* Types should NOT be written in the docstring — use type hints instead.
+**Use Google-style docstrings with Args section for all public functions.**
-Bad:
+❌ **Insufficient Documentation:**
```python
def send_email(to, msg):
"""Send an email to a recipient."""
```
-Good:
+✅ **Complete Documentation:**
```python
-def send_email(to: str, msg: str) -> None:
+def send_email(to: str, msg: str, *, priority: str = "normal") -> bool:
"""
- Sends an email to a recipient.
+ Send an email to a recipient with specified priority.
Args:
to: The email address of the recipient.
- msg: The message body.
+ msg: The message body to send.
+ priority: Email priority level (``'low'``, ``'normal'``, ``'high'``).
+
+ Returns:
+ True if email was sent successfully, False otherwise.
+
+ Raises:
+ InvalidEmailError: If the email address format is invalid.
+ SMTPConnectionError: If unable to connect to email server.
"""
```
+**Documentation Guidelines:**
+
+- Types go in function signatures, NOT in docstrings
+- Focus on "why" rather than "what" in descriptions
+- Document all parameters, return values, and exceptions
+- Keep descriptions concise but clear
+- Use reStructuredText for docstrings to enable rich formatting
+
📌 *Tip:* Keep descriptions concise but clear. Only document return values if non-obvious.
----
+### 6. Architectural Improvements
-### 6. Propose Better Designs When Applicable
+**When you encounter code that could be improved, suggest better designs:**
-* If there's a **cleaner**, **more scalable**, or **simpler** design, highlight it.
-* Suggest improvements, even if they require some refactoring — especially if the new code would:
+❌ **Poor Design:**
- * Reduce duplication
- * Make unit testing easier
- * Improve separation of concerns
- * Add clarity without adding complexity
+```python
+def process_data(data, db_conn, email_client, logger):
+ # Function doing too many things
+ validated = validate_data(data)
+ result = db_conn.save(validated)
+ email_client.send_notification(result)
+ logger.log(f"Processed {len(data)} items")
+ return result
+```
-Instead of:
+✅ **Better Design:**
```python
-def save(data, db_conn):
- # manually serializes fields
+@dataclass
+class ProcessingResult:
+ """Result of data processing operation."""
+ items_processed: int
+ success: bool
+ errors: List[str] = field(default_factory=list)
+
+class DataProcessor:
+ """Handles data validation, storage, and notification."""
+
+ def __init__(self, db_conn: Database, email_client: EmailClient):
+ self.db = db_conn
+ self.email = email_client
+
+ def process(self, data: List[dict]) -> ProcessingResult:
+ """Process and store data with notifications."""
+ validated = self._validate_data(data)
+ result = self.db.save(validated)
+ self._notify_completion(result)
+ return result
+```
+
+**Design Improvement Areas:**
+
+If there's a **cleaner**, **more scalable**, or **simpler** design, highlight it and suggest improvements that would:
+
+- Reduce code duplication through shared utilities
+- Make unit testing easier
+- Improve separation of concerns (single responsibility)
+- Make unit testing easier through dependency injection
+- Add clarity without adding complexity
+- Prefer dataclasses for structured data
+
+## Development Tools & Commands
+
+### Package Management
+
+```bash
+# Add package
+uv add package-name
+
+# Sync project dependencies
+uv sync
+uv lock
+```
+
+### Testing
+
+```bash
+# Run unit tests (no network)
+make test
+
+# Don't run integration tests, as API keys must be set
+
+# Run specific test file
+uv run --group test pytest tests/unit_tests/test_specific.py
+```
+
+### Code Quality
+
+```bash
+# Lint code
+make lint
+
+# Format code
+make format
+
+# Type checking
+uv run --group lint mypy .
+```
+
+### Dependency Management Patterns
+
+**Local Development Dependencies:**
+
+```toml
+[tool.uv.sources]
+langchain-core = { path = "../core", editable = true }
+langchain-tests = { path = "../standard-tests", editable = true }
```
-You might suggest:
+**For tools, use the `@tool` decorator from `langchain_core.tools`:**
```python
-# Suggest using dataclasses or Pydantic for automatic serialization and validation
+from langchain_core.tools import tool
+
+@tool
+def search_database(query: str) -> str:
+ """Search the database for relevant information.
+
+ Args:
+ query: The search query string.
+ """
+ # Implementation here
+ return results
```
-### 7. Misc
+## Commit Standards
+
+**Use Conventional Commits format for PR titles:**
+
+- `feat(core): add multi-tenant support`
+- `fix(cli): resolve flag parsing error`
+- `docs: update API usage examples`
+- `docs(openai): update API usage examples`
+
+## Framework-Specific Guidelines
+
+- Follow the existing patterns in `langchain-core` for base abstractions
+- Use `langchain_core.callbacks` for execution tracking
+- Implement proper streaming support where applicable
+- Avoid deprecated components like legacy `LLMChain`
+
+### Partner Integrations
+
+- Follow the established patterns in existing partner libraries
+- Implement standard interfaces (`BaseChatModel`, `BaseEmbeddings`, etc.)
+- Include comprehensive integration tests
+- Document API key requirements and authentication
+
+---
+
+## Quick Reference Checklist
+
+Before submitting code changes:
-* When suggesting package installation commands, use `uv pip install` as this project uses `uv`.
-* When creating tools for agents, use the @tool decorator from langchain_core.tools. The tool's docstring serves as its functional description for the agent.
-* Avoid suggesting deprecated components, such as the legacy LLMChain.
-* We use Conventional Commits format for pull request titles. Example PR titles:
- * feat(core): add multi‐tenant support
- * fix(cli): resolve flag parsing error
- * docs: update API usage examples
- * docs(openai): update API usage examples
+- [ ] **Breaking Changes**: Verified no public API changes
+- [ ] **Type Hints**: All functions have complete type annotations
+- [ ] **Tests**: New functionality is fully tested
+- [ ] **Security**: No dangerous patterns (eval, silent failures, etc.)
+- [ ] **Documentation**: Google-style docstrings for public functions
+- [ ] **Code Quality**: `make lint` and `make format` pass
+- [ ] **Architecture**: Suggested improvements where applicable
+- [ ] **Commit Message**: Follows Conventional Commits format