doc: state the design philosophy and the doc-sync rule for contributors

.github/PULL_REQUEST_TEMPLATE.md

@@ -65,3 +65,5 @@ For example:
 - [ ]  `Doc - TODO` <!-- Your PR changes impact docs and you will update later -->
 - [ ]  `Doc - Done` <!-- Related docs have been already added or updated -->
 - [ ]  `Doc - No Need` <!-- Your PR changes don't impact/need docs -->
+
+Related hugegraph-doc PR or issue: <!-- required for Doc - TODO and Doc - Done -->

AGENTS.md

@@ -83,6 +83,18 @@ mvn test -pl hugegraph-store/hg-store-test -am
 
 Before writing new tests, check existing suites under `hugegraph-server/hugegraph-test/`.
 
+## Design philosophy
+
+Match the codebase, do not improve on it.
+
+- Extend existing code before introducing a new abstraction. A new interface, factory
+  or base class needs a reason beyond symmetry.
+- Keep the change minimal: the smallest edit that fully solves the issue. Adjacent
+  cleanups belong in their own PR.
+- One concern per PR. Do not bundle an unrelated fix because you were already in the file.
+- Comments stay short. When something needs real context to explain, link the GitHub
+  issue instead of writing a paragraph in the source.
+
 ## Style & Pre-commit
 
 - Line 120, 4-space indent, LF, UTF-8, **no star imports**
@@ -101,6 +113,10 @@ Before writing new tests, check existing suites under `hugegraph-server/hugegrap
   and `install-dist/scripts/dependency/known-dependencies.txt`.
 - `hugegraph-commons` is shared by every module; `hugegraph-struct` must precede PD/Store;
   server backends depend on `hugegraph-core`.
+- Feature, config and `Dockerfile` changes ship a paired PR in `apache/hugegraph-doc`.
+  Land both together; docs that trail the code go stale without anyone noticing.
+- README: wrap at 120, keep it thin, push detail to hugegraph-doc, and fold the
+  non-urgent parts into `<details>`.
 
 ## Additional context files
 

docs/CONTRIBUTING.md

@@ -125,6 +125,12 @@ Note that since GitHub requires submitting code through `username + token` (inst
 
 Go to the web page of GitHub fork repo, there would be a chance to create a Pull Request after pushing to a new branch, click the button "Compare & pull request" to do it. Then edit the description for proposed changes, which can just be copied from the commit message.
 
+If the change touches a feature, a configuration item or a `Dockerfile`, open the matching
+documentation PR in [hugegraph-doc](https://github.com/apache/hugegraph-doc) at the same time
+and link the two together. Both should merge together. Documentation that trails the code
+goes stale quietly, and the gap is only found when a user or a search tool reads the wrong
+thing.
+
 Note: please make sure the email address you used to submit the code is bound to the GitHub account. For how to bind the email address, please refer to https://github.com/settings/emails:
 <img width="1280" alt="image" src="https://user-images.githubusercontent.com/9625821/163522445-2a50a72a-dea2-434f-9868-3a0d40d0d037.png">