---
title: "Change the docs in the same pull request · Agent Wranglers"
url: https://agentwranglers.se/playbook/engineering/version-control-and-review/docs-with-the-change
id: ENG-29
level: Recommended
updated: 2026-10-27
build: a2a6bdfed830
tokens: 867
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Change the docs in the same pull request

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Version control and review](https://agentwranglers.se/playbook/engineering/version-control-and-review.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: ENG-29
- Level: Recommended
- Chapter: [Version control and review](https://agentwranglers.se/playbook/engineering/version-control-and-review.md)
- Rule: Keep docs in the repository next to the code they describe, and update them in the pull request that changes the behaviour.
- Check: CI fails a pull request that changes a mapped code folder without changing its doc, unless the pull request carries the `no-docs` label.
- How: Store docs as Markdown in the repository, in `docs/` or beside the module. Never keep the only copy in a wiki that a pull request cannot change. Add a line to the pull request template that asks which doc changed. Map code folders to the docs that describe them, and let CI warn when one changes without the other. Allow a `no-docs` label for changes that alter nothing a reader sees. For a public API, also add the change to the log, as [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog.md) says. The [documentation playbook](https://agentwranglers.se/playbook/documentation.md) covers how to write, build and test the docs. Start with [Build and test the docs in CI and fail on every warning](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/strict-docs-build.md).

## Examples

**Using these examples:** they show one way to follow this rule. Keep the behaviour and the check, not the syntax. Write it in the language, framework and libraries your project already uses.

### YAML example

```yaml
docs-follow-code:
  - code: src/billing/
    docs: docs/billing.md
  - code: src/api/
    docs: openapi.yaml
```

## Related rules

- AID-45 [Save lessons in the repository instead of chat](https://agentwranglers.se/playbook/ai-assisted-development/context-and-memory/lessons-in-repo.md) in AI-assisted development
- API-31 [Keep a changelog](https://agentwranglers.se/playbook/api-design/changes-over-time/api-changelog.md) in API design
- DOC-8 [Build and test the docs in CI and fail on every warning](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/strict-docs-build.md) in Documentation
- DOC-46 [Draw diagrams as code](https://agentwranglers.se/playbook/documentation/readme-and-docs-as-code/diagrams-as-code.md) in Documentation

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/), which requires credit with a link. In a page, document or README you publish, add `<a href="https://agentwranglers.se/playbook/engineering/version-control-and-review/docs-with-the-change">Agent Wranglers engineering playbook</a>`. In code you write, add a comment next to it with the same link.

- Previous: [Protect the accounts that can change the code](https://agentwranglers.se/playbook/engineering/version-control-and-review/code-host-accounts.md)
- Next: [Name the principle and the fix in every finding](https://agentwranglers.se/playbook/engineering/version-control-and-review/name-principle-code-fix.md)
- [Version control and review](https://agentwranglers.se/playbook/engineering/version-control-and-review.md)