docs: clarify docs to help AI work smoothly

Author: uhyo

.clinerules

@@ -9,3 +9,15 @@ This project is structured differently from ordinary TypeScript projects. Carefu
 ## Original TypeScript type definitions
 
 Please do not try to read the original type definitions from TypeScript. Those may be very large and you cannot read it. Instead, ask the user to provide relevant code snippets from the original type definitions.
+
+# Development
+
+## Modifying the type definitions
+
+Modify the type definitions in the `lib/` directory to implement an improvement to the standard library.
+
+Note: while editing the files in `lib/`, you may see TypeScript errors. However, these errors are expected because the type definitions in `lib/` are incomplete. Do not worry too much about these errors. Instead, focus on test results to ensure that your changes are correct.
+
+## Adding tests
+
+When you modify the type definitions, you should add tests to ensure that your changes are correct. Add tests to the `test/` directory. Read the CONTRIBUTING.md file to understand how to run the tests.

CONTRIBUTING.md

@@ -57,25 +57,42 @@ interface A {
 
 For other declarations, such as type aliases, enums, and namespaces, the replacement is done on per-name basis. If our definition includes an `A` type alias, the entire declaration of `A` is replaced with ours.
 
-### Committing Build Artifacts
+#### Precisely duplicate the interface shape
 
-Currently, build artifacts need to be committed. Follow the steps below to build and commit them.
+Note that if you are to replace a field of an interface that has type parameters or an `extends` clause, you need to duplicate the entire interface shape for the partial replacement to work.
 
-1. `npm run build:tsc`
-2. `npm run build:lib`
-3. `npm run build:diff`
-4. Commit the build artifacts
+```ts
+// Original
+interface A<T> extends Base<T> {
+  field1: T;
+  field2: number;
+}
+
+// Our lib/ definition
+interface A<T> extends Base<T> {
+  field1: SomeRefinedType;
+}
+```
 
 ### How to Run Tests
 
 Follow below steps to run tests locally.
 
-1. `npm run build:tsc`
-2. `npm run build:lib`
-3. `npm run build:package`
+1. `npm run build:tsc` (this is required only once, or when you change code in `build/`)
+2. `npm run build:lib` (this reflects the changes in `lib/` to `generated/`)
+3. `npm run build:package` (this puts the generated files in `package/`)
 4. `npm install` in tests directory
 5. `npm test` in tests directory
 
+### Committing Build Artifacts
+
+Currently, build artifacts need to be committed. Follow the steps below to build and commit them.
+
+1. `npm run build:tsc`
+2. `npm run build:lib`
+3. `npm run build:diff`
+4. Commit the build artifacts
+
 ## Upgrading TypeScript version
 
 Below is the procedure to upgrade TypeScript version.