248 lines
12 KiB
Markdown
248 lines
12 KiB
Markdown
# Mandatory Skill Routing
|
|
|
|
Skills are mandatory procedures, not optional reference material.
|
|
|
|
Before performing any specialized operation, identify the applicable skill(s)
|
|
and read their `SKILL.md` before executing the operation.
|
|
|
|
Examples of specialized operations include:
|
|
- building;
|
|
- running tests;
|
|
- C/C++ semantic analysis;
|
|
- compiler-diagnostic analysis;
|
|
- debugging;
|
|
- code generation.
|
|
|
|
If an applicable skill exists:
|
|
- MUST use that skill.
|
|
- MUST NOT construct an alternative procedure from memory.
|
|
- MUST NOT silently substitute another tool or workflow.
|
|
- MUST follow the skill's preconditions before executing its commands.
|
|
|
|
If no applicable skill can be identified for an operation that requires one:
|
|
report this to the user and STOP before performing that operation.
|
|
|
|
# General Workflow
|
|
|
|
- **User Guidance:** Proactively communicate your plan and the reason for each
|
|
step.
|
|
- **File Creation Pre-check:** Before creating any new file, you MUST first
|
|
perform a thorough search for existing files that can be modified or
|
|
extended. This is especially critical for tests; never create a new test file
|
|
if one already exists for the component in question. Always add new tests to
|
|
the existing test file.
|
|
- **Read Before Write/Edit:** **ALWAYS** read the entire file content
|
|
immediately before writing or editing.
|
|
- **Problems on the way:** **ALWAYS** report to user if something is not working
|
|
as expected from Skills or AGENTS.md
|
|
- **Missing in environment:** **ALWAYS** report to user if something is missing
|
|
in work environment
|
|
|
|
## Hard Stops
|
|
|
|
An unexpected command failure is terminal for the current turn. This includes a
|
|
non-zero exit status, a missing required tool or configuration, an unavailable
|
|
service, malformed required output, or a denied permission, unless the user
|
|
explicitly asked to investigate that failure.
|
|
|
|
On such a failure, immediately report the command or operation, its exit status
|
|
or failure condition, and the complete preserved failure output or its log
|
|
location. Then STOP. Do not retry, substitute a command, run further diagnosis,
|
|
kill a process, clean output, regenerate configuration, or edit code until the
|
|
user gives a new instruction.
|
|
|
|
For C/C++ edits, a language-server diagnostic error is also a hard stop before
|
|
any build. Use the applicable diagnostic skill to run diagnostics for every
|
|
modified C/C++ source or header file. Report all errors and warnings; do not
|
|
build while any error remains or when diagnostics cannot be run.
|
|
|
|
## Standard Edit/Fix Workflow
|
|
|
|
**IMPORTANT:** This workflow takes precedence over all other coding
|
|
instructions. Read and follow everything strictly without skipping steps
|
|
whenever code editing is involved. Any skipping requires a proactive message to
|
|
the user about the reason to skip.
|
|
|
|
1. **Comprehensive Code and Task Understanding (MANDATORY FIRST STEP):** Before
|
|
writing or modifying any code, you MUST perform the following analysis to
|
|
ensure comprehensive understanding of the relevant code and the task. This
|
|
is a non-negotiable prerequisite for all coding tasks.
|
|
- **a. Identify the Core Files:** Locate the files that are most relevant to
|
|
the user's request. All analysis starts from these files.
|
|
- **b. Conduct a Full Audit:**
|
|
- **IMPORTANT** For deeper understanding language server should be used if available.
|
|
- Read the full source of **EVERY** core file.
|
|
- For each core file, summarize the control flow and ownership semantics.
|
|
State the intended purpose of the core file.
|
|
- **c. State Your Understanding:** After completing the audit, you should
|
|
briefly state the core files you have reviewed, confirming your
|
|
understanding of the data flow and component interactions before proposing
|
|
a plan.
|
|
- **d. Anti-Patterns to AVOID:**
|
|
- **NEVER** assume the behavior of a function or class from its name or
|
|
from usage in other files. **ALWAYS** read the source implementation.
|
|
- **ALWAYS** check at least one call-site for a function or class to
|
|
understand its usage. The context is as important as the implementation.
|
|
2. **Make Change:** After a comprehensive code and task understanding, apply the
|
|
edit or write the file.
|
|
- When making code edits, focus **ONLY** on code edits that directly solve
|
|
the task prompted by the user.
|
|
- After modifying C/C++ source or header files, run the applicable
|
|
language-server diagnostics before proceeding to a build. Follow the
|
|
**Hard Stops** section if diagnostics find an error or cannot run.
|
|
3. **Write/Update Tests:**
|
|
- First, search for existing tests related to the modified code and update
|
|
them as needed to reflect the changes.
|
|
- If no relevant tests exist, write new unit tests or integration tests if
|
|
it's reasonable and beneficial for the change made.
|
|
- If tests are deemed not applicable for a specific change (e.g., a trivial
|
|
comment update), explicitly state this and the reason why before moving to
|
|
the next step.
|
|
4. **Build:** **ALWAYS** build relevant targets after making edits.
|
|
5. **Fix compile errors:** **ALWAYS** follow these steps to fix compile errors.
|
|
- **ALWAYS** take the time to fully understand the problem before making any
|
|
fixes.
|
|
- **ALWAYS** read at least one new file for each compile error.
|
|
- **ALWAYS** find, read, and understand **ALL** files related to each
|
|
compile error. For example, if an error is related to a missing member of
|
|
a class, find the file that defines the interface for the class, read the
|
|
whole file, and then create a high-level summary of the file that outlines
|
|
all core concepts. Come up with a plan to fix the error.
|
|
- **ALWAYS** check the conversation history to see if this same error
|
|
occurred earlier, and analyze previous solutions to see why they didn't
|
|
work.
|
|
- **NEVER** make speculative fixes. You should be confident before applying
|
|
any fix that it will work. If you are not confident, read more files.
|
|
6. **Test:** **ALWAYS** run relevant tests after a successful build. If you
|
|
cannot find any relevant test files, you may prompt the user to ask how this
|
|
change should be tested.
|
|
7. **Fix test errors:**
|
|
- **ALWAYS** take the time to fully understand the problem before making any
|
|
fixes.
|
|
8. **Iterate:** Repeat building and testing using the above steps until all are
|
|
successful.
|
|
|
|
# Chromium Directives
|
|
|
|
## Paths
|
|
|
|
- All files in Chromium's source can be read by substituting `chromium/src` or
|
|
`//` for the current workspace (which can be determined by running
|
|
`gclient root` and appending `/src` to the output).
|
|
|
|
## Building
|
|
|
|
- Do not attempt a build without first establishing the correct output
|
|
directory and target. If you have not been given them, and you plan on doing
|
|
a build, then stop and ask before starting on any other tasks.
|
|
- Unless otherwise instructed, ask user for build environment details
|
|
- Immediately before launching a Chromium build, use the applicable build
|
|
skill's pre-launch procedure to verify the configured locations, environment
|
|
variables, wrapper, output directory, and target.
|
|
- Check for an existing Chromium build before launching a new one. If one is
|
|
running, report it and STOP. Never kill, restart, or replace a running build
|
|
without the user's explicit permission.
|
|
- When reporting build status from a log, cite only output produced after the
|
|
current build session was launched. Do not treat earlier log sessions as
|
|
evidence about the current build.
|
|
|
|
## Testing
|
|
|
|
Unless otherwise instructed, ask user on test running details
|
|
|
|
When using `tools/autotest.py`:
|
|
- Do not invoke `autoninja` beforehand because `autotest.py` automatically
|
|
builds relevant targets.
|
|
- Build targets containing colons (`:`) are not valid inputs for
|
|
`{RELEVANT_TEST_FILENAMES}`.
|
|
|
|
## Coding
|
|
|
|
- Stay on task: Do not address code health issues or TODOs in code unless it is
|
|
required to achieve your given task.
|
|
- Add code comments sparingly: Focus on *why* something is done, not *what* is
|
|
done.
|
|
|
|
# Knowledge Base (adapted from `agents/prompts/knowledge_base.md`)
|
|
|
|
You MUST NOT answer from your general knowledge alone. The Chromium codebase is
|
|
vast and specific. Before answering any query, consult the relevant docs and
|
|
source. Canonical documentation is in `docs/`, and Chromium-specific docs exist
|
|
throughout `docs/`.
|
|
|
|
Use this guide to decide which documents to consult:
|
|
|
|
## Core Programming Patterns
|
|
|
|
- **Communication between components/processes (e.g., browser-to-renderer):**
|
|
Look for **Mojo IPC interfaces (`.mojom` files)** that define the protocol
|
|
between components. Read the `.mojom` file to understand the data structures
|
|
and methods.
|
|
- **Asynchronous operations or threading:** Look for usage of
|
|
`base::TaskRunner` and `base::BindOnce`/`base::BindRepeating` for posting
|
|
tasks to the correct sequence or thread.
|
|
- **Code inside `third_party/blink/renderer/`:**
|
|
Blink has its own memory management and containers. **You MUST use container
|
|
and string types from `third_party/blink/renderer/platform/wtf/`** (e.g.,
|
|
`blink::Vector`, `blink::String`) and **Oilpan for GC** (`Member<>`,
|
|
`WeakMember<>`, `Persistent<>`). **DO NOT** use STL containers or most `base/`
|
|
equivalents inside Blink code.
|
|
- **Threading/Callbacks:**
|
|
- Threading (`base::Thread`, `base::TaskRunner`, `base::PostTask`, sequences):
|
|
consult `docs/threading_and_tasks.md`.
|
|
- Callbacks (`base::OnceCallback`, `base::RepeatingCallback`, `base::Bind`):
|
|
consult `docs/callback.md`.
|
|
|
|
## Adding a User Preference (Pref)
|
|
For prefs/settings (`pref`, `preference`, `setting`, `PrefService`): consult
|
|
`components/prefs/README.md`.
|
|
|
|
## Adding a New UMA Metric
|
|
|
|
- For UMA histograms/metrics: consult `docs/metrics/uma/README.md`.
|
|
|
|
## Modifying BUILD.gn files
|
|
|
|
- For style/best practices: consult `docs/imported/gn/style_guide.md`.
|
|
|
|
## Adding a New UKM Metric
|
|
|
|
- For UKM metrics: consult `tools/metrics/ukm/README.md`.
|
|
|
|
## Debugging
|
|
|
|
- **Header file not found:**
|
|
1. Verify `deps` in the `BUILD.gn` of the failing target.
|
|
2. Verify the `#include` path.
|
|
3. (Infer from Target System Skill, if presented) Regenerate build files: `gn gen <out_dir>`.
|
|
4. (Infer from Target System Skill, if presented) Confirm GN sees the dep: `gn desc <out_dir> //failing:target deps`.
|
|
5. (Infer from Target System Skill, if presented) Check for issues: `gn check <out_dir> //failing:target`.
|
|
- **Linker error (undefined symbol):** check the target providing the symbol is
|
|
in `deps` (`gn desc`), and that `is_component_build` is set as expected in
|
|
`args.gn`.
|
|
- **Visibility error:** add the depending target to `visibility` in the
|
|
dependency's `BUILD.gn`.
|
|
- **General runtime debugging:** consult `docs/debugging.md`.
|
|
|
|
# Landmines
|
|
|
|
These rules exist because certain commands are too slow or crash/hang agents on
|
|
Chromium's large source tree, or because they are destructive.
|
|
|
|
- Read files one at a time with the `read` tool. Do not batch-read or echo out
|
|
the entire contents of many large files in one turn.
|
|
- Any time you want to use `grep -r`, `grep -R`, or `git grep`, use `rg`
|
|
instead.
|
|
- Any time you want to use `find`, use `fdfind` instead.
|
|
- If running `rg` or `fdfind` fails because the executables are missing, tell
|
|
the user to install them with the following command, and then stop:
|
|
```
|
|
sudo apt-get install ripgrep fd-find
|
|
```
|
|
- Never directly install software with `brew` or `apt-get` - instead suggest
|
|
the required installation to the user with the full command line, and then
|
|
stop.
|
|
- Never amend git commits (`git commit --amend`). Always create new ones.
|
|
- Do not use recursive directory-wide searches that hang on this tree; prefer
|
|
targeted `rg`/`fdfind` queries.
|