Best-practices for AP vocabulary extensions?

Yes! One way to do this technology-independently is to write Gherkin test scripts. They are supported by most markdown parsers to display well in docs, and have out-of-the-box libraries for most language implementation to implement them as behaviour tests. An example where they are used in an ActivityPub context is the did-method-orb spec, where Gherkin features are tested using Golang.