Skip to content

Updated GEMINI.md #407

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kyasbal merged 1 commit into from
Dec 8, 2025
Merged

Updated GEMINI.md #407

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
123 changes: 6 additions & 117 deletions GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,132 +1,22 @@
> **Note:** In this document, "I" refers to the Gemini assistant, and "you" refers to the user.

# Gemini's Operating Manual

> **As Gemini, I will strictly adhere to the following principles when executing user instructions. These principles form the foundation for all subsequent rules.**

## Core Operating Principles

1. **Phase Declaration:**
* As the most important principle, I will **always state the current PDCA phase and step at the beginning of every response.** This ensures transparency and keeps my actions aligned with the defined procedure.
* The format will be:

```text
==== HEADER ====
* I, Gemini, will now begin 【P: PLAN】 - Planning Phase, Step 2: **File Analysis**.
* According to GEMINI.md, the key points for this step are as follows:
* (Relevant points from GEMINI.md)
================


* (Details of the work)

==== FOOTER ===
* This concludes the log for this step. The next step is ...
(If another PDCA cycle is executed while one is in progress, output the current PDCA cycle status like a stack trace.)
(When one or more steps are skipped, write the justification to skip the step.)
===============
---
```

2. **Thorough PDCA Cycle (Plan-Do-Check-Act):** I will systematically and reliably execute all tasks according to the following PDCA cycle.

* **【P: PLAN】 - Planning Phase:** The goal is to accurately understand the user's request and create a concrete, executable plan.
* **Step 1: Requirement Analysis:** Analyze the user's intent and objectives. Ask clarifying questions if anything is ambiguous.
* If there are any unclear or ambiguous points, ask the user the necessary questions to create a viable plan.
* Even if there are no ambiguities, list at least three points that are inferred from common sense but not explicitly included in the user's instructions.
* **Step 2: File Analysis:** Review necessary files to understand the task, even if previously read.
* **Step 3: Information Search:** Search official documentation for APIs, commands, etc. with `GoogleSearch` tool. and share findings with URLs.
* **Step 4: Task Decomposition & Planning:** Break down the task into concrete steps and present a detailed plan, including files to be modified, implementation outlines, and the verification plan for the CHECK phase.
* **Step 5: Consensus:** Obtain the user's approval of the plan before proceeding to the DO phase.

* **【D: DO】 - Execution Phase:** The goal is to accurately execute the plan agreed upon in the PLAN phase.
* **Step 1: Faithful Execution:** Strictly follow the plan. No unplanned changes.
* **Step 2: Clear Code Display:** Present generated or modified code in language-specified blocks, showing context for partial changes.
* **Step 3: Add Comments:** Add comments to explain the intent of important or complex logic.

* **【C: CHECK】 - Evaluation Phase:** The goal is to objectively verify that the execution results meet quality standards and requirements.
* **Step 1: Mandatory Verification:** **Always run build, static analysis (lint), and tests (unit/integration).** Skipping these is not permitted. If a check fails, this step is restarted after the fix.
* **Step 2: Report Results:** Clearly report the success/failure of each verification step.
* **Example Output:**
* `make build-go`: `Success`
* `make lint-go`: `Success`
* `make test-go`: `Failure (1 out of 2 failed)`
* **Step 3: Provide Error Details:** If verification fails, **always** provide the error messages, logs, and stack traces needed to identify the cause.
* If any corrections are made, always restart from Step 1.
* **Step 4: Review of Corrections:** If any changes were made to resolve a failure in the CHECK phase, summarize the specific changes.

* **【A: ACT】 - Improvement & Summary Phase:** The goal is to summarize the completed work, report the current status, and define the next action.
* **Step 1: Summarize Completed Tasks:** Briefly report the work completed in the cycle.
* **Step 2: Summarize User Corrections:** Summarize any corrections the user made during the cycle and propose updates to this `GEMINI.md` if necessary.
* **Step 3: Report Current Status:** Report the overall project progress and current state.
* **Step 4: Propose Next Steps:** Propose the next task for the next PDCA cycle, or declare completion if all tasks are finished.

3. **Final User Confirmation:**
* When I believe all tasks are complete, I will not state, "I am finished."
* Instead, I will summarize the work performed and delegate the final judgment to the user.

4. **User Confirmation Before Git Commit:**
* Executing the `git commit` command is permitted only with the user's explicit approval.
* Before executing a commit, I must present the following information and ask the user, "Is it okay to execute the commit?"
* **Proposed Commit Message:** A message drafted according to the conventions in `GEMINI.md`.
* **Diff of Changes to be Committed:** The output of `git diff --staged` (or `git diff HEAD`).
* Attempting to commit without user approval is strictly forbidden.

## Development Process

* **Discussion and Planning:** The discussion and planning phase before writing code is crucial. When instructed, I will provide concrete code examples as much as possible and seek your guidance.
* Specifically, the plan must always include:
* If data structure changes are involved, show the changes with code examples.
* A test plan. Planning for tests is essential when writing code. List the items to be tested.
* **Critical Feedback Welcome:** Please actively provide critical feedback on my proposals from the following perspectives:
* Testability; if possible, propose methods that would make future testing easier.
* **Incremental Verification:** I will not make large changes at once. Instead, I will make changes in small, functional, or logical units. After each small change, I will run the relevant verification steps to ensure the project remains in a healthy state. This leads to early problem detection and easier debugging.
* **After Code Edits (`.go`, `.ts`, etc.):** I will run the relevant linters (`make lint-go` / `make lint-web`) and tests (`make test-go` / `make test-web`).
* **After Documentation Edits (`.md`):** After I edit any Markdown file (including this one), I will run `make lint-markdown` to check for formatting and style issues.

## Tool Usage Principles

* **File Editing:** When modifying existing files, especially collaboratively edited files like `GEMINI.md`, do not carelessly overwrite the entire file with `write_file`. First, read the current content with `read_file` to check for user changes, then use the `replace` tool to update only the differences. This prevents unintentional overwrites.
* **Non-ASCII Character Verification:** When editing files containing non-ASCII characters like Japanese, text corruption may occur. To detect and correct this, the following procedure must be followed:
1. Immediately after executing `write_file` or `replace`, **always re-read the written content using `read_file`**.
2. Verify that the re-read content perfectly matches the intended written content.
3. In the unlikely event that corruption is confirmed, immediately overwrite the file again with the correct content to fix it. Do not proceed to other tasks until this correction is complete. (If `write_file` or `replace` cannot solve the problem, use commands like `sed` to resolve it).
* **Safe Execution of Multi-line Shell Commands:** To safely pass multi-line strings to shell commands like `git commit`, I will use the `printf` command combined with a pipe (`|`). This method is more robust than using here-documents within the `run_shell_command` tool.

When constructing the string for `printf`, I must pay close attention to shell expansions and escape sequences.
* **Newlines** must be explicitly written as `\n`.
* **Special characters**: Quotes (`"` and `'`) within the message must be properly escaped with a backslash (`\`) to prevent shell misinterpretation. Do not use backticks (`) in the message.
# Kubernetes History Inspector (KHI) Developer Guide

```bash
# Example: Using printf with proper escaping
printf "feat(gemini): add new rule\n\nThis commit's body contains a \"quoted\" word." | git commit -F -
```

* **Handling of Long-Running Commands:** To ensure stable and predictable interactions, my execution of shell commands is guided by the following principles:
* **Verification with Single-Run Commands:** For verifying my changes, I will prioritize single-run, terminating commands (e.g., `make build`, `make test`, `make lint`). These provide clear success or failure results.
* **Requesting Long-Running Tasks:** I will **not** directly execute long-running commands that do not terminate on their own (e.g., `make watch-web`, `ng test`). Instead, I will request that you, the user, run these commands in your own terminal. This prevents my CLI from becoming blocked and ensures you have full control over these processes.

---

# Part 1: Project Overview
## Part 1: Project Overview

## Project Purpose

Kubernetes History Inspector (KHI) is a log visualization tool for Kubernetes clusters.
It visualizes large volumes of logs in interactive timeline views, providing powerful support for troubleshooting complex issues that span multiple components within a Kubernetes cluster.

It does not require the installation of agents in the cluster. By simply loading the logs, it provides log visualizations useful for troubleshooting.
It visualizes large volumes of logs in interactive timeline views, providing powerful support for troubleshooting complex issues that span multiple components within a Kubernetes By simply loading the logs, it provides log visualizations useful for troubleshooting.
Comment thread
kyasbal marked this conversation as resolved.

## Primary Technology Stack

* **Backend:** Go
* **Frontend:** Angular, TypeScript
* **Frontend:** Angular 20, TypeScript
* **Build:** Makefile, npm
* **Container:** Docker

---

# Part 2: Getting Started
## Part 2: Getting Started

## Setup Instructions

Expand Down Expand Up @@ -209,7 +99,7 @@ The frontend development server is started with `make watch-web`.

---

# Part 3: Development Workflow & Conventions
## Part 3: Development Workflow & Conventions

## Coding Conventions

Expand All @@ -234,7 +124,6 @@ Please follow Google's coding conventions as much as possible.
* Use the **`input()`** signal function for component inputs instead of the `@Input` decorator.
* Prefer **Signals** over RxJS for component-level state management.
* In templates, use built-in control flow (**`@for`**, **`@if`**) over structural directives (`*ngFor`, `*ngIf`).
* TODO: Specify compliance with a style guide (e.g., Angular Style Guide).

### Sass (SCSS)

Expand Down
41 changes: 20 additions & 21 deletions pkg/GEMINI.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,3 @@
> **Note:** In this document, "I" refers to the Gemini assistant, and "you" refers to the user.

# GEMINI.md for `pkg` Directory

This document outlines the development conventions and guidelines specific to the `pkg` directory. All code within this directory must adhere to these rules, in addition to the global standards defined in the root [`GEMINI.md`](../GEMINI.md).
Expand All @@ -8,37 +6,22 @@ This document outlines the development conventions and guidelines specific to th

The `pkg` directory contains the core business logic of the Kubernetes History Inspector, written in Go. It is organized into several packages, each with a distinct responsibility.

**Note:** The package structure is currently undergoing a refactoring. Please be aware that the project is in a transitional state.

### Current Structure

The following is the current, high-level structure:

- **`common`**: Provides generic, reusable components and utilities that are not specific to this application's domain (e.g., collections, concurrent data structures, time helpers).
- **`inspection`**: Manages the inspection process, including task running, server management, and data handling.
- **`log`**: Defines the structured logging format and provides utilities for parsing and handling log entries.
- **`model`**: Contains the primary data models for Kubernetes objects, historical events, and their compositions.
- **`parser`**: Implements log parsing logic for various log formats.
- **`source`**: Handles fetching data from various sources, such as local files or Google Cloud Storage.
- **... (other packages)**: Refer to the source code and godoc for details on other packages.

### Future Refactoring Plan

We are moving towards the following structure. When adding new functionality, please adhere to this future plan.

- **`common`**: Provides generic, reusable components and utilities. **This package must not depend on any other `pkg/` packages.**
- **`common`**: Provides generic, reusable components and utilities that are not specific to this application's domain (e.g., collections, concurrent data structures, time helpers). **This package must not depend on any other `pkg/` packages.**
- **`core`**: Contains the fundamental components of KHI's task system.
- **`task`**: Defines the generic Directed Acyclic Graph (DAG) mechanism, independent of specific tasks. It is only allowed to depend on `pkg/common`.
- **`inspection`**: Manages the task graph for log inspection. It is only allowed to depend on `pkg/common` and `pkg/core/task`.
- **`app`**: Manages the task graph for the KHI application lifecycle. It is only allowed to depend on `pkg/common` and `pkg/core/task`.
- **`task`**: Contains all packages that define the concrete DAGs for KHI.
- **`contract`**: Defines task label IDs and other elements used in the generic DAG system. It is only allowed to depend on `pkg/common` and `pkg/core/task`.
- **`inspection`**: Defines the specific tasks for the log inspection DAG.
- **`app`**: Defines the specific tasks for the application lifecycle DAG.
- **`test`**: Contains helper packages for KHI's tests. All package names under this directory must end with `_test`. These are utilities; the tests themselves are located in `_test.go` files within the same folder as the code they test. **Code outside of the `test` directory is forbidden from importing these packages.**
- **`testutil`**: Contains helper packages for KHI's tests. All package names under this directory must end with `_test`. These are utilities; the tests themselves are located in `_test.go` files within the same folder as the code they test. **Code outside of the `testutil` directory is forbidden from importing these packages.**
- **`task`**: Provides testing utilities for the generic task graph.
- **`inspection`**: Provides testing utilities for the log inspection task components.
- **`app`**: Provides testing utilities for the application lifecycle task components.
- **`model`**: Contains the primary data models for Kubernetes objects, historical events, and their compositions.
- **`server`**: Contains the HTTP server implementation.

## 2. Coding Conventions

Expand All @@ -59,13 +42,29 @@ We follow Google's Go coding standards and the conventions outlined in the root

- **Interfaces**: Interface names should end with `-er` or `-or` (e.g., `Reader`, `Inspector`) or be named to reflect their purpose without a specific suffix if the implementation is not important to the caller.
- **Structs**: Structs that implement an interface should be named logically. For example, the implementation for a `Reader` interface might be `fileReader` or `gcsReader`.
- **Packages**:
- Packages under `pkg/task/inspection` should follow the naming convention `[provider][resource_type]` (e.g., `googlecloudclustergke`, `ossclusterk8s`).
- `resource_type` should be `log[log_type]` if the task is not specific to cluster type but commonly used by multiple cluster types.
- `resource_type` should be `cluster[cluster_type]` if the task is specific to cluster type.
- Folders directly under `pkg/task/inspection` contians `impl` and `contract` folders.
- `impl` folder should contain the implementation of the task.
- `contract` folder should contain the contract of the task(Task ID and types used as results in the task).
- `contract` folder should not depend on `impl` folder.
- `contract` folder package name is `[provider][resource_type]_contract`.
- `impl` folder package name is `[provider][resource_type]_impl`.
- **Task Implementation**:
- Task implementation files should end with `_task.go`.
- Task IDs should be defined in `contract/taskid.go`.

## 3. Testing Strategy

- **Unit Tests**: All public functions and significant internal logic must be covered by unit tests. Test files should be named `_test.go`.
- **Avoid Assertion Libraries**: Do not use third-party assertion libraries. Check conditions using simple `if` statements and report test failures with standard functions like `t.Errorf()` or `t.Fatalf()`.
- **Complex Struct Comparison**: Use `cmp.Diff` from `github.com/google/go-cmp/cmp` when comparing complex structs.
- **Prefer Table-Driven Tests**: Structure tests as table-driven tests. Define a test case struct within the test function and iterate over a slice of test cases, calling `t.Run()` for each one.
- **ChangeSet Comparison**: When testing `history.ChangeSet`, use `testchangeset.ChangeSetAsserter` and its implementations (e.g., `HasRevision`, `HasEvent`) from `pkg/testutil/testchangeset`.
- **Test Utilities**: Use the `testutil` package for common test setup and helper functions. Avoid duplicating test logic.
- **Task Testing**: Use `tasktest` and `inspectiontest` packages for testing tasks. See `pkg/task/inspection/googlecloudclustergke/impl/autocompletegkeclusternames_task_test.go` for a reference implementation.
- **Mocks**: When testing interactions between packages, use interfaces and mock implementations.
- **Skipping Tests**: For tests that require external dependencies (like Cloud Logging), use the `-skip-cloud-logging=true` flag as documented in the root `GEMINI.md`. Ensure such tests are properly tagged.

Expand Down
Loading