Merge pull request #1010 from LalatenduMohanty/concise-docs-guidance

docs(agents): reduce duplication and add concise writing guidance

Author: LalatenduMohanty

AGENTS.md

@@ -2,88 +2,58 @@
 
 > **Note**: This file is also available as `CLAUDE.md` (symlink) for Claude Code CLI users.
 >
-> **IMPORTANT**: Before making any code changes, you MUST read [CONTRIBUTING.md](CONTRIBUTING.md) for comprehensive coding standards and design patterns. This file provides essential quick reference only.
-
-## When to Read CONTRIBUTING.md
-
-**Always read CONTRIBUTING.md before:**
-
-- Writing new functions (for type annotation standards)
-- Adding imports (for import organization rules)
-- Creating tests (for testing patterns)
-- Making commits (for commit message format)
-- Adding error handling or logging
+> Read [CONTRIBUTING.md](CONTRIBUTING.md) for comprehensive coding standards, design patterns, and commit message format. This file provides agent-specific quick reference only.
 
 ## Essential Rules (MUST FOLLOW)
 
 ### Do
 
+- Keep all written text concise and easy to understand — docstrings, comments, commit messages, PR descriptions, and documentation
 - Add docstrings on all public functions and classes
 - Use file-scoped commands for fast feedback (see below)
-- Follow existing patterns - search codebase for similar code
+- Follow existing patterns — search codebase for similar code
 - Chain exceptions: `raise ValueError(...) from err`
 - Use `req_ctxvar_context()` for per-requirement logging
-- Run `hatch run lint:fix` to format code (handles line length, whitespace, etc.)
+- Run `hatch run lint:fix` to format code
 
 ### Don't
 
 - Don't run full test suite for small changes (use file-scoped)
 - Don't create temporary helper scripts or workarounds
 - Don't commit without running quality checks
-- Don't make large speculative changes without asking
+- Don't make large speculative changes — ask first or propose a plan
 - Don't update git config or force push to main
-- Don't use bare `except:` - always specify exception types
+- Don't use bare `except:` — always specify exception types
+- Don't invent new patterns — search the codebase for existing ones
 
 ## Commands (IMPORTANT: Use File-Scoped First)
 
-### Setup Commands (Run Once)
+### Setup (Run Once)
 
 ```bash
-# Install pre-commit hooks for automatic file formatting
-hatch run lint:install-hooks
+hatch run lint:install-hooks    # Pre-commit hooks for automatic formatting
 ```
 
-### File-Scoped Commands (PREFER THESE)
+### File-Scoped (PREFER THESE)
 
 ```bash
-# Type check single file
-hatch run mypy:check <filepath>
-
-# Format single file
-hatch run lint:fix <filepath>
-
-# Test specific file
-hatch run test:test tests/test_<module>.py
-
-# Test specific function
-hatch run test:test tests/test_<module>.py::test_function_name
-
-# Debug test with verbose output
-hatch run test:test <filepath> --log-level DEBUG
+hatch run mypy:check <filepath>                          # Type check single file
+hatch run lint:fix <filepath>                            # Format single file
+hatch run test:test tests/test_<module>.py               # Test specific file
+hatch run test:test tests/test_<module>.py::test_name    # Test specific function
+hatch run test:test <filepath> --log-level DEBUG         # Debug test
 ```
 
-### Project-Wide Commands (ASK BEFORE RUNNING)
+### Project-Wide (ASK BEFORE RUNNING)
 
 ```bash
 hatch run lint:fix       # Format all code
 hatch run test:test      # Full test suite (slow!)
 hatch run mypy:check     # Type check everything
 hatch run lint:check     # Final lint check
-hatch run lint:precommit # All linters and other pre-commit hooks
+hatch run lint:precommit # All linters and pre-commit hooks
 ```
 
-### Pre-commit Hooks
-
-Run all linters and formatters via pre-commit:
-
-```bash
-hatch run lint:precommit    # Run all hooks manually
-```
-
-Pre-commit runs automatically on commit after installation with `hatch run lint:install-hooks`.
-
-**Markdown formatting:** The mdformat hook formats Markdown files using a pure Python formatter with GitHub Flavored Markdown support.
-
 ## Safety and Permissions
 
 ### Allowed Without Asking
@@ -104,14 +74,14 @@ Pre-commit runs automatically on commit after installation with `hatch run lint:
 
 ## Project Structure
 
-- `src/fromager/` - Main package code
-- `tests/` - Unit tests (mirror `src/` structure)
-- `e2e/` - End-to-end integration tests
-- `docs/` - Sphinx documentation
+- `src/fromager/` — Main package code
+- `tests/` — Unit tests (mirror `src/` structure)
+- `e2e/` — End-to-end integration tests
+- `docs/` — Sphinx documentation
 
 ### Reference Files for Patterns
 
-**Before writing code, look at these examples:**
+Look at these before writing code:
 
 - Type annotations: `src/fromager/context.py`
 - Pydantic models: `src/fromager/packagesettings.py`
@@ -121,112 +91,33 @@ Pre-commit runs automatically on commit after installation with `hatch run lint:
 
 ## Code Patterns
 
-**Import Guidelines (ALWAYS FOLLOW):**
-
-- **PEP 8: imports should be at the top**: All import statements MUST be placed at the top of the file, after module docstrings and before other code. This applies to ALL Python files in the project.
-- **No local imports**: Do not place import statements inside functions, methods, or conditional blocks under any circumstances
-
-### Testing Pattern
-
-```python
-def test_behavior(tmp_path: pathlib.Path) -> None:
-    """Verify expected behavior."""
-    # Arrange
-    config = tmp_path / "config.txt"
-    config.write_text("key=value\n")
-    # Act
-    result = load_config(config)
-    # Assert
-    assert result["key"] == "value"
-```
-
-## Commit Message Format (REQUIRED)
-
-Use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) format:
-
-```text
-<type>(<scope>): <short summary>
-
-<body explaining what + why>
+**Import rules:** All imports at the top of the file, no local imports. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
 
-<footer: Closes: #123>
-```
+**Testing:** Use Arrange/Act/Assert pattern, name functions `test_<behavior>()`. See `tests/test_context.py` for examples.
 
-### Types
+## Commit Messages
 
-- **feat**: new functionality
-- **fix**: bug fix
-- **docs**: documentation only
-- **test**: tests only
-- **refactor**: behavioral no-op refactor
-- **perf**: performance improvement
-- **chore**: tooling or dependency change
+Follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) — see [CONTRIBUTING.md](CONTRIBUTING.md) for format, types, and examples.
 
-### Good Examples
+When AI agents create or significantly modify code, add attribution:
 
 ```text
-feat(resolver): add exponential backoff for HTTP retries
-
-Improves resilience when PyPI is under load by adding jittered backoff.
-
-Closes: #123
-```
-
-```text
-fix(constraints): handle missing constraint file gracefully
-
-Validate file existence and emit helpful message instead of crashing.
-```
+feat(scope): short summary
 
-### AI Agent Attribution
-
-When AI agents create or significantly modify code, add attribution using `Co-Authored-By`:
-
-```text
-feat(resolver): add exponential backoff for HTTP retries
-
-Improves resilience when PyPI is under load by adding jittered backoff.
+Body explaining what and why.
 
 Co-Authored-By: Claude <claude@anthropic.com>
 Closes: #123
 ```
 
-### Bad Examples (NEVER DO THIS)
-
-- `fix bug` (too vague)
-- `updated files` (not descriptive)
-- `WIP` (not informative)
-- `fixed the thing that was broken` (not professional)
-
 ## Workflow for Complex Tasks
 
 1. **Search codebase** for similar patterns first
-2. **Create a checklist** in a markdown file for tracking
-3. **Work through items systematically** one at a time
+2. **Create a checklist** for tracking progress
+3. **Work through items** one at a time
 4. **Run file-scoped tests** after each change
-5. **Check off completed items** before moving to next
-6. **Run full quality checks** only at the end
-
-## When Uncertain
-
-- Ask clarifying questions rather than making assumptions
-- Search the codebase for similar patterns before inventing new ones
-- Propose a specific plan before making large changes
-- Reference [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidance
-- **DO NOT** make large speculative changes without confirmation
-
-## Quality Checklist Before Finishing
-
-- [ ] Read CONTRIBUTING.md for relevant standards
-- [ ] Type annotations on all functions
-- [ ] Docstrings on public APIs
-- [ ] Tests cover the change
-- [ ] File-scoped tests pass
-- [ ] No trailing whitespace
-- [ ] File ends with single newline
-- [ ] Conventional Commit format used
-- [ ] Full quality checks pass: `hatch run lint:fix && hatch run test:test && hatch run mypy:check && hatch run lint:check`
+5. **Run full quality checks** only at the end: `hatch run lint:fix && hatch run test:test && hatch run mypy:check && hatch run lint:check`
 
 ---
 
-**See [CONTRIBUTING.md](CONTRIBUTING.md) for comprehensive standards, detailed examples, and design patterns used in Fromager.**
+**See [CONTRIBUTING.md](CONTRIBUTING.md) for comprehensive standards, detailed examples, and design patterns.**