chromium-ai-assisted/AGENTS.md

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.