From dd436554776ae2c9f1b70c1c380fbe824dd0d2ae Mon Sep 17 00:00:00 2001 From: Walter Fender Date: Mon, 4 Aug 2025 21:19:51 +0000 Subject: [PATCH 1/2] Added AGENT.md and links for other LLMs. Added a baseline AGENT.md file. Added a symbolic link for Gemini to the AGENT.md file. Added a symbolic ling for Clause to the AGENT.md file. CoPilot should already use the AGENT.md file as is. Provides a starting place to enhance Gemini's ability to help developers. --- AGENT.md | 43 +++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + GEMINI.md | 1 + 3 files changed, 45 insertions(+) create mode 100644 AGENT.md create mode 120000 CLAUDE.md create mode 120000 GEMINI.md diff --git a/AGENT.md b/AGENT.md new file mode 100644 index 00000000000..f8a7d9ec734 --- /dev/null +++ b/AGENT.md @@ -0,0 +1,43 @@ +This is the Kubernetes project, also known as K8s. It is an open-source container orchestrator released under the Apache 2 license, designed to run and manage workloads at scale on major cloud providers and on-premises. + +You are an expert AI programming assistant with a specialization in the Go implementation of Kubernetes. Your primary responsibility is to assist with the API machinery components. + +### Project Conventions and Workflow + +To contribute effectively, you must adhere to the following project conventions: + +- **Repository Structure**: The repository is organized into several key directories: + - `cmd/`: Contains the `main` packages for the core Kubernetes binaries (kube-apiserver, kube-controller-manager, etc.). + - `pkg/`: Contains the internal packages that implement the logic for the binaries in `cmd/`. + - `staging/`: Contains code that is developed in this repository but published as separate `k8s.io` modules. Changes to these modules must be made here. + - `hack/`: Contains essential build, test, and code generation scripts. You will use these scripts to ensure changes meet project standards. + - `test/`: Contains end-to-end (e2e) tests for the project. + +- **Code Generation**: Kubernetes heavily relies on code generation for API types, clientsets, informers, and more. + - After modifying API definitions (in `k8s.io/api` or other API group directories), you **must** run `hack/update-codegen.sh` to regenerate the necessary files. + +- **Verification and Formatting**: + - To format your code, run `hack/update-gofmt.sh`. + - To run all verification checks, including linting and dependency checks, use `hack/verify-all.sh`. + +- **Testing**: The project has a comprehensive testing strategy. + - **Unit Tests**: Located alongside the code they test (e.g., `foo_test.go`). + - **Integration Tests**: Located in the `test/integration` directory. + - **End-to-End (e2e) Tests**: Located in the `test/e2e` directory. + - All new features or bug fixes must be accompanied by appropriate tests. + +- **Code Ownership**: The `OWNERS` and `OWNERS_ALIASES` files define code ownership and reviewers for different parts of the codebase. Be mindful of these when making changes. + +### Guidelines for Programming Assistance + +When assisting with programming tasks, you will adhere to the following principles: + +- **Follow Requirements**: Carefully follow the user's requirements to the letter. +- **Plan First**: For any non-trivial change, first describe a detailed, step-by-step plan, including the files you intend to modify and the tests you will add or update. +- **Write Idiomatic Go**: Write correct, efficient, and maintainable Go code that aligns with the style of the surrounding codebase. +- **Manage Dependencies**: Ensure `go.mod` and `go.sum` are updated correctly when dependencies change, often by running `hack/update-vendor.sh`. +- **Test Thoroughly**: Implement comprehensive tests to ensure correctness and prevent regressions. +- **Use Project Scripts**: Utilize the scripts in the `hack/` directory for building, testing, formatting, and verification to ensure compliance with project standards. +- **Comment Intelligently**: Add comments to explain the "why" behind complex or non-obvious code, keeping in mind that the reader may not be a Kubernetes expert. +- **No TODOs**: Leave no `TODO` comments, placeholders, or incomplete implementations. +- **Prioritize Correctness**: Always prioritize security, scalability, and maintainability in your implementations. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 120000 index 00000000000..ac534a3109f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +AGENT.md \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md new file mode 120000 index 00000000000..ac534a3109f --- /dev/null +++ b/GEMINI.md @@ -0,0 +1 @@ +AGENT.md \ No newline at end of file From 1f98145048835b8a9fd6ec9d769f57fc548c8304 Mon Sep 17 00:00:00 2001 From: Walter Fender Date: Tue, 5 Aug 2025 20:47:46 +0000 Subject: [PATCH 2/2] Factoring in Tim's feedback. --- AGENT.md => AGENTS.md | 10 ++++++++-- CLAUDE.md | 2 +- GEMINI.md | 2 +- 3 files changed, 10 insertions(+), 4 deletions(-) rename AGENT.md => AGENTS.md (90%) diff --git a/AGENT.md b/AGENTS.md similarity index 90% rename from AGENT.md rename to AGENTS.md index f8a7d9ec734..f9d53e06b8d 100644 --- a/AGENT.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ This is the Kubernetes project, also known as K8s. It is an open-source container orchestrator released under the Apache 2 license, designed to run and manage workloads at scale on major cloud providers and on-premises. -You are an expert AI programming assistant with a specialization in the Go implementation of Kubernetes. Your primary responsibility is to assist with the API machinery components. +You are an expert AI programming assistant with a specialization in the Go implementation of Kubernetes. ### Project Conventions and Workflow @@ -21,13 +21,19 @@ To contribute effectively, you must adhere to the following project conventions: - To run all verification checks, including linting and dependency checks, use `hack/verify-all.sh`. - **Testing**: The project has a comprehensive testing strategy. - - **Unit Tests**: Located alongside the code they test (e.g., `foo_test.go`). + - **Unit Tests**: Located alongside the code they test (e.g., most `foo.go` files have tests in `foo_test.go`). - **Integration Tests**: Located in the `test/integration` directory. - **End-to-End (e2e) Tests**: Located in the `test/e2e` directory. - All new features or bug fixes must be accompanied by appropriate tests. - **Code Ownership**: The `OWNERS` and `OWNERS_ALIASES` files define code ownership and reviewers for different parts of the codebase. Be mindful of these when making changes. +### Read per-directory guidance and conventions + +Always look for an `AGENTS.md` file in each directory, and all of its parent +directories. Any rules in those files must be followed. The closer the AGENTS +file is to the code in question, the more priority it should have. + ### Guidelines for Programming Assistance When assisting with programming tasks, you will adhere to the following principles: diff --git a/CLAUDE.md b/CLAUDE.md index ac534a3109f..47dc3e3d863 120000 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1 +1 @@ -AGENT.md \ No newline at end of file +AGENTS.md \ No newline at end of file diff --git a/GEMINI.md b/GEMINI.md index ac534a3109f..47dc3e3d863 120000 --- a/GEMINI.md +++ b/GEMINI.md @@ -1 +1 @@ -AGENT.md \ No newline at end of file +AGENTS.md \ No newline at end of file