From 539992f88127e5c25689b49b2aecf1758b887cea Mon Sep 17 00:00:00 2001
From: Jeremy Kubica <104161096+jeremykubica@users.noreply.github.com>
Date: Fri, 9 Oct 2026 09:26:19 -0400
Subject: [PATCH] Add a basic development guide markdown

---
 copier.yml                                    |  8 +++
 docs/index.rst                                |  1 +
 docs/practices/development_guide.rst          | 37 ++++++++++
 ...ude_dev_guide %}AGENTS.md{% endif %}.jinja |  3 +
 ...de %}DEVELOPMENT_GUIDE.md{% endif %}.jinja | 68 +++++++++++++++++++
 5 files changed, 117 insertions(+)
 create mode 100644 docs/practices/development_guide.rst
 create mode 100644 python-project-template/{% if include_dev_guide %}AGENTS.md{% endif %}.jinja
 create mode 100644 python-project-template/{% if include_dev_guide %}DEVELOPMENT_GUIDE.md{% endif %}.jinja

diff --git a/copier.yml b/copier.yml
index ff255dc..4cef954 100644
--- a/copier.yml
+++ b/copier.yml
@@ -142,6 +142,14 @@ include_notebooks:
         no: false
     when: "{{ include_docs }}"
 
+include_dev_guide:
+    help: Do you want to include a development guide markdown file for your repository?
+    type: bool
+    default: yes
+    choices:
+        yes: true
+        no: false
+
 include_benchmarks:
     help: Do you want to enable benchmarking?
     type: bool
diff --git a/docs/index.rst b/docs/index.rst
index efde6fb..233c867 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -53,4 +53,5 @@ please :doc:`/source/contact`
    practices/sphinx
    practices/publishing_package
    practices/customizing_project
+   practices/development_guide
 
diff --git a/docs/practices/development_guide.rst b/docs/practices/development_guide.rst
new file mode 100644
index 0000000..8a592e0
--- /dev/null
+++ b/docs/practices/development_guide.rst
@@ -0,0 +1,37 @@
+Development Guide Files
+===============================================================================
+
+What is it? Why do it?
+-------------------------------------------------------------------------------
+
+Development guide files are markdown files that can be used by both humans and AI agents to provide guidance on development practices within a project. They can explain high level design decisions, help ensure consistency, and describe the best practices used throughout the project. When used in combination with AI agents, these files can both optimize the development workflow (by providing overviews) and assist in maintaining high code quality standards.
+
+Developers should extend this file and add information as the project progresses to capture the current state of both the code and the best practices.
+
+
+Common Sections
+-------------------------------------------------------------------------------
+
+We recommend including sections on the following topics:
+
+- Overview of the project, including how it is structured, its main components, and how it will be used.
+- Design "North Stars" (key guiding principles for the project's development)
+- How to set up the development environment
+- How to run tests and linting (common commands)
+- Repository structure (especially for projects with subdirectories)
+- Coding standards and style guidelines
+- Project specific considerations such as default units.
+
+Default Information
+-------------------------------------------------------------------------------
+
+The default DEVELOPMENT_GUIDE.md file is generated with recommendations and principles corresponding to the Python Project Template.
+
+For example, the default "North Stars" provided are:
+- Correctness is the Top Priority.
+- Code should be modular and use a few consistent APIs.
+- Make Easy Things Easy, Hard Things Possible.
+- Code should follow a standard format.
+- Code should be documented.
+
+Developers should edit any of the information in the DEVELOPMENT_GUIDE.md file to reflect their design goals and philosophy.
diff --git a/python-project-template/{% if include_dev_guide %}AGENTS.md{% endif %}.jinja b/python-project-template/{% if include_dev_guide %}AGENTS.md{% endif %}.jinja
new file mode 100644
index 0000000..30e7f5e
--- /dev/null
+++ b/python-project-template/{% if include_dev_guide %}AGENTS.md{% endif %}.jinja	
@@ -0,0 +1,3 @@
+# Agent Instructions
+
+Read [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) before making any changes. It is the canonical reference and may include information on design principles, core abstractions, API conventions, development workflow, and best-practices.
diff --git a/python-project-template/{% if include_dev_guide %}DEVELOPMENT_GUIDE.md{% endif %}.jinja b/python-project-template/{% if include_dev_guide %}DEVELOPMENT_GUIDE.md{% endif %}.jinja
new file mode 100644
index 0000000..da6d001
--- /dev/null
+++ b/python-project-template/{% if include_dev_guide %}DEVELOPMENT_GUIDE.md{% endif %}.jinja	
@@ -0,0 +1,68 @@
+# {{project_name}} Development Guide
+
+This document provides a guide for contributing to the development of this project, and can include information such as design principles, core abstractions, API conventions, development workflow, and best-practices.
+
+## Design Goals and North Stars
+**CRITICAL: Always keep these design principles in mind when making changes to the project.**
+
+**Correctness is the Top Priority.** The code should include thorough tests. Any approximations should be clearly documented and communicated to the user.
+
+**Code should be modular and use a few consistent APIs.**
+
+**Make Easy Things Easy, Hard Things Possible.** Common use cases should require minimal configuration or set up, but users should also be able to perform complex work.
+
+**Code should follow a standard format** with automatic formatting supported by `ruff`.
+
+**Code should be documented.** Docstrings should provide sufficient API information, such as parameter explanations, for users to understand the code.
+
+
+
+## Common Commands
+
+```bash
+# All tests
+python -m pytest
+
+# Parallel tests
+python -m pytest -n auto
+
+# Lint and format (let the linter fix style — do not hand-tune)
+{% if 'ruff_lint' in enforce_style or 'ruff_format' in enforce_style -%}
+ruff check src/ tests/
+ruff format src/ tests/
+{% endif -%}
+{% if 'black' in enforce_style -%}
+black src/
+black test/
+{% endif -%}
+
+
+# Pre-commit (runs ruff lint/format, workflow/pyproject schema checks, pytest, etc.)
+pre-commit run --all-files
+
+{% if include_docs -%}
+# Build docs
+sphinx-build -M html ./docs ./_readthedocs
+{% endif -%}
+```
+
+## Repository Structure
+
+```
+src/{{package_name}}/             Main package
+tests/{{package_name}}/           Test suite
+{% if include_docs -%}
+docs/                             Sphinx documentation sources
+{% endif -%}
+{% if include_benchmarks -%}
+benchmarks/                       ASV performance benchmarks
+{% endif -%}
+```
+
+
+## Testing Conventions
+
+- **File naming:** `tests/{{package_name}}/<SUBDIR>/test_<name>.py`, mirroring the `src/{{package_name}}/` layout.
+- **Fixtures:** defined in `tests/conftest.py`. Use existing fixtures, do not duplicate test data.
+- Default test run: `python -m pytest`
+